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1 The Authorization Server 



1.1 Introduction 

The Authorization Server has the responsibility of authenicating a user's identity by cheeking a login name 
and password against the list of recoginzed users and their passwords. This version of the Authorization 
server is only temporary. The temporary Authorization Server runs on a remote PERQ so that if that PERQ is 
down then the Authorization Server will not be running. This Authorization Server identifies each user with 
a unique id. A user may have owner or world access privileges. This is described in the Introduction to the 
Spice User's Manual. The Authorization Server that will be implemented in the future is described in the 
Sesame: The Spice File System Manual and will include group access privileges. 

1.2 Type Definitions 

The following type are defined in Authdefs.pas. 
Auth Var Size = 30; 

No.User =0; { files owned by "nobody" } 

First.User =1; { first valid user } 

Type 

Auth.Var = String[Auth_Var.Size]; 

User.ID = No User..Max Users; { must be "bitlO" } 

PassType = Long; { a two word value } 

{ 4 chars f or a password??? } 

UserRecord = record 

Name: Auth.Var; { Name of the user } 
UserlD: User.ID; { The user ID of the user. } 
EncryptPass: PassType; { The encrypted password. } 
Profile: APath.Name; { Path name of the profile file. } 
NameOfShell: APath.Name; { Name of the ShellRUN File. } 
End; 

Machine.Name = String[255]; 

Check Type = (Check.Login, { user is logging in } 
Check.User); { user is changing parameters } 

Logged.User = record { one logged- in user } 

UserlD :User.ID; 
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UserName :Auth_Var; 
MachineName :Auth_Var; 
End; 

Logged_User_ Array = array [0..0] of Logged.User; 
Logged.User List = tLogged_User Array; 



CONST 

Auth_Error Base = 5000; 



UserNameNotFound = Auth_Error_Base + 1; 
PassWordlncorrect = Auth_Error Base + 2; 
AuthPortlncorrect = Auth_Error Base + 3; 



13 Routines 



The following functions and procedures are found in Authuser.pas. 

InitAuth 



Call: 

procedure InitAuth( 

RPort : Port) 

Parameters: 

RPort 

ARunLoad initializes a process address space from RunFileName (or from a run file structure in memory ifp 
is not nil), and optionally starts it executing. 
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LoginUser 

Logs a user into the authentication server. 
Call: 

procedure LoginUser( 

ServPort : Port; 
UserName : Auth _Var; 
Password : Auth_Var; 
MachineName :Auth_Var; 
var UserAuthPort : Port; * 
var UserRec : UserRecord) 
: GeneralReturn 

Parameters: 
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Results: 



ServPort-Thc authentication server port 
UserName-thQ name of the user to check 
Password-^assv^ord for the user 
MachineName 

UserAuthPort-Port returned to the user if the name and password 
match 

UserRec-ls filled with the user information if the user name and 
password match 

Success- Valid user, logged in 
o//ier-Invalid user 



WI HIB I M i BHSIEMl 

Logs a user out 
Call: 



Parameters: 



Results: 



LogoutUser 



function LogoutUser( 

ServPort : Port) 
: GeneralReturn 



ServPort-The port for the authentication server. 
Succejs-AuthPortlncorrect 



ConflrmUser 

Checks the UserAuthPort to ensure that the user is logged in If so, returns useful information about the user 
Call: 



function ConfirmUser( 

ServPort : Port; 
UserAuthPort : Port; 
var Userld : User ID; 
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var UscrMachineName: Auth Var) 
: GeneralReturn 

Parameters: 

ServPort-The port for the authentication server 

UserAuthPort-thz signature port 

UserlD-Retums the ID number for the user 

UserMachineName-Retiims the name for the machine that the user is 
logged on. 

Results: 

Success-if the user is valid 



CheckUser 

Verifies a user name/pasword pair and returns information about that user. 
Call: 

function CheckUser( 

ServPort : Port; 
UserName: AuthJVar; 
Password : Auth. Var; 
var UserRec : UserRecord) 
: GeneralReturn 

Parameters: 

ServPort-Thz authentication server port 
UserName-usQT name to be checked 
Password-password for the user 

UserRec-ls filled with user information if the user name and 
password match. 

Results: 

Success-Valid user 
ctf/ier-Invalid user 



ChangeUserParams 
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This function changes the parameters for a logged- in user. 
Call: 



Parameters: 



Results: 



function ChangeUserParams( 

ServPort : Port; 
UserName : Port; 
CurrentPassword: Auth.Var; 
ChangcPassword : Boolean; 
NewPassword: Auth _Var; 
NewProflle: APath_Name; 
NewShell : APath_Name) 
: GeneralReturn 



ServPort-The port for the user's authentication server. 
UserName-'Na.mQ of the user whose information is to be changed 
CurrentPassword-cunent password in the user's record 
ChangePassword-lf true, change password 
NewPassword-new password to replace the current one 
NewProfile-path name of the profile file for the user 
NewShell-namQ of the shell to be stored in the user record. 

Success-if the user was added or changed. 

AuthPortlncorrect-lf the user did not have the proper access rights to add or change 
a user. 



GetUserName 

Gets the user name corresponding to a User ID, 
Call: 

function GetUserName( 

ServPort : Port; 
Userld : User .ID; 
var UserName: Auth_Var) 
: QenejalReHiia 

Parameters: 
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Serv/'ort-Authentication Port Server 
UserlD-UserlD 

UserName-RQtums the name for the user 

Results: 

Success 

UserNameNotFound 



ListLoggedlnUsers 

Returns all of the users currently logged in to this Authentication Server. 
Call: 

function ListLoggedInUsers( 

ServPort : Port; 
varUserList : Logged JJserList; 
var UserList_Cnt: long) 
: GeneralRetura 



Parameters: 



Results: 



ServA?rt-Authentication server port 
UserList-Rctums a list of user- ID-Machine 
{/,serL/s/_Oi/-Returns the number of users logged in. 

Success 



27 Aug 84 



Servers-7 



2 The Environment Manager 
2.1 Introduction 

The Environment Manager provides a language and process independent way of sharing directory 
searchlists and other variables among different processes executing on one machine. 
The Environment Manager provides a message interface to define and retrieve environment variables. An 
environment variable is a named variable that has a type, a scope, and a set of values associated with it 
There are two types: a string- valued variable and a searchlist. The values of the variables are kept as a 
variable-length array of strings. An environment variable has a scope associated with it, either local or 
global. A local variable is seen only by a single process. The local environment of the parent is copied at 
process creation time and is passed to the child process. Once the copy is made, any subsequest changes are 
not shared between parent and child. Only global variables can be shared between processes. Global 
variables are visible to all the processes that are served by the Environment Manager. 

A String-valued variable simply allows one to store and retrieve arbitrary strings. 

A Searchlist-valued variable is a list of directories to be searched when looking for a file. The entries in a 
searchlist are either directory names or names of other searchlists. On lookup, all references to searchlists 
are expanded (replaced by their contents) until the expanded searchlist consists only of directory names. An 
entry that is a reference to a searchlist contains the name of the searchlist followed by a colon (Y) (and 
optionally a subdirectory name). This is the same syntax that is used by the file system to denote searchlists. 
It is possible to have both a local and global environment variable with the same name. In this case the local 
variable takes precedent just as in Pascal scope rules. 

Ordinarily, if a local searchlist exists with the same name as a global searchlist, the local searchlist will be 
used. The one exception to this rule is that when a local searchlist contains its own name, that becomes a 
reference to the global searchlist with the same name - not a recursive reference to itself. This behavior is 
useful because it allows the system to specify a default search list for a given subsystem by name and for 
that subsystem to reference its path by that name. However, a user may then define a local searchlist with 
the same name to override the normal search list for that system. The user can then use the global definition 
from within the local definition, allowing the user to add directories to the normal search list for the 
subsystem. 

Note that this applies even if the original searchlist is a global search list For example, Accent searches for 
run files within the "Run:" search list and all other files within the "Default:" search list. A user who wants 
to make both searchlists the same can define the global "Run:" search list as "Default:". Then, each time 
the "Run:" search list is resolved, the sytem will actually search the "Default:" search list for the process 
asking for the search. Since the "Default:" search list is first resolved locally, this allows the one (global) 
definition of the "Run:" search list to refer to different "Default:" search lists depending on which process 
resolves it 
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2.2 Definitions 

The following definitions are found in EnvMgrDefs.pas. 

At the shell level, Searchlist environment variable names are distinguished from string environment 
variable names by having a colon (':') as the last character of the name. This colon is NOT used by any of 
the Environment Manager user interface calls and is not returned by ScanEnv Variables. 

{ Env_ Variable: A list of environment entries, each of which is a string, 
const 

Env_Elcment_Size = 255; { MaxString } 
type 

Env Element = string[Env_ElementSize]; 

Env_Elcment_ Array = array [0 .. 0] of Env_Element; { hack } 

Env_Variable = t Env_Element_ Array; 

{ A Searchlist name embedded in a searchlist string is followed by 
{ a Searchlist.Separator character. 

const 

Searchlist.Separator = 



{ Env_Var_Name: The name string for an environment variable. 
{ The syntax of the name is the same as for an arbitrary 
{ entry name in the name server. 

const 

Env_VarName_Size = Entry.Name.Size; 
type 

Env_Var_Name = string[Env_VarName_Size]; 



{ Env.Var.Type: The environment variable type values. 



Env.Var.Type = ( 
Env_String, { Values are lists of strings } 
Env.SearchList); { Value is a search list } 



{ Env.Var.Scope: Flag specifying whether to find environment variable 
{ in the local table, global table, or using the normal method 
{ of local and then global. 

type 

Env.Var.Scope = ( 
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EnvNormal, 

Env_Local, 

EnvGlobal); 



{ Use the normal lookup method } 
{ Refer to name in per-process table } 
{ Refer to name in global environment 



variable table } 



{ Env_Scan_List: A list of environment variable names, types, and scopes. 



EnvScan.Record = 
record 

VarName : Env_Var_Name; 
VarType : Env_Var_Type; 
VarScope : Env_Var_Scope; 
end; 

En v_Scan_ Array = array [0 .. 0] of Env_Scan_Record; { hack } 
Env_Scan.List = t Env_Scan_ Array; 



{ Error return values for Environment Manager. 



const 

Env.Error Base = 1600; 

EnvVariableNotFound = Env_ErrorBase + 1; 
WrongEnvVarType = Env_Error Base + 2; 
BadSearchlistSyntax = EnvError Base + 3; 
SearchlistLoop = Env_Error Base + 4; 
FirstltemNotDefined = Env_Error Base + 5; 

23 Functions 

The following functions are found in EnvMgrUser.pas. 



Returns the value of an environment variable. If the variable is a searchlisU this does not evaluate any 
contained searchlist references. 

Call: 



type 



GetEnvVariable 



Function GetEnvVariable( 



ServPort : Port; 

Name : Env .VarName; 

SearchScope: Env.Var_Scope; 



var Variable : Env_Variable; 
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var Variable _Cnt: long; 
varVarTypc : Env_Var_Type; 
var ActualScopc: Env_Var_Scope) 
: GeneralRetum 

Parameters: 

Sen Port-Connection to the Environment Manager for process. 

Name-name of environment variable. 

SearchScope-wheve to search: 

Env_Global global environment only 

Env_Local local environment only 

Env Normal Search the local environment If 

the variable is not there, search the 

global environment. 

Variable-returns a pointer to the variable (a variable-length 
array of strings). 

Variable Cnt-xetmns the number of entries in variable. 

VarType-xetwws, type of environment variable: Env_Searchlist 
or Env_String. 

ActualScope-retums where the variable was actually found 
(Env_Local or EnvGlobal). 

Results: 

Success 

Environment Variable not found 



SetEnvVariable 

Enters a new environment variable. If the variable is a search list, checks for valid search list syntax and 
ensures that each entry ends in a directory separator ("/") or a searchlist terminator (":"). 

Call: 

Function SetEnvVariable( 

ServPort :Port; 
Name : Env.VarName; 
VarType : Env.Var.Type; 
VarScope : Env.Var.Scope; 
Variable : Env_Variable; 
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Variable _Cnt: long) 
: GeneralReturn 

Parameters: 

ServPort-Connection to the Environment Manager for process. 

Name-name of environment variable. 

VarType-type of variable to enter: 

Env_String or Env_Searchlist 

VarScope- Where to enter the variable: 

Env,Global global environment 
Env Local local environment 

Variable-pointer to the variable (a variable-length array of 
strings). 

Variable Cnt-number of elements in variable. If the value is an 
empty array, the name is deleted. 

Results: 

S access 

BadName-\f search list name is null or if an entry is malformed. Null 
search list names are ignored. 



ResolveSearchList 

The ResolveSearchList call is used to resolve the value of an environment variable of type EnvSearchList, 
recursively expanding any environment variable references contained therein. If undefined names are 
encountered during the expansion, they are ignored and the expansion is continued It is, however, an error if 
the evaluation results in an empty search list 

Caii: 

Function ResolveSearchList 
ServPort : Port; 
Name : Env.Var.Name; 
FirstOnly : boolean; 
var Variable : EnvJVariable; 
var Variable _Cnt : long; 
varFirstDefined : boolean) 
: GeneralReturn 

Parameters: 
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ServPort-Port for process environment 
Name-name of search list. 

FirstOnly-if TRUE, only return the first item in the expansion. If 
FALSE, return all items in the expansion. 

^an^/e-returns a pointer to the search list (a variable-length 
array of directory names). 

Variable Cni-TQtums the number of entries in search list 

First Defined-TCtums TRUE if the first element in the expansion exists. 
Returns FALSE is it could not be resolved (it was a reference to a 
search list that did not exist). 

Results: 

Success 

SearchListnotfound 
WrongEnvVarType 
SearchListLoop 

ScanEnvVariables 

Lists the defined environment variables by name. 
Call: 

Function ScanEnvVariables( 
ServPort :Port; 
SearchScope: Env_Var.Scope; 
EnvScanList: Env_Scan_List; 
var EnvScanList _Cnt: long) 
: GeneralReturn 

Parameters: 

ServPort-Pon for process environment 

SearchScope-Env Global list global variables only 
Env_Local list local variables only 
Env .Normal list all local variables, and all 
global variables that are not hidden 
by local variables with the same 
names. 
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Results: 



EnvScanList-VQUirns the list of variable names, types, and scopes. 
EnvScanListC >rt-returns the number of entries in EnvScanLisL 

Success 



CopyEnvConnection 

Creates a new connection to the SearchList manager, copying all of the local variables belonging to the old 
connection. 



Call: 



Parameters: 



Results: 



Function CopyEnvConnection( 
ServPort : Port; 
OldConnection : Port; 
var NewConnection : port) 
: GeneralReturn 



ServPort-Any port to the Environment Manager. 

OldConnection-port designating parent connection. If it is NullPort, 
the new connection will have no local variables; 
otherwise, it will receive copies of all the local 
variables from OldConnection. 

NewConnection-retums port for new connection. 



Success 

NoMoreConnections 



EnvDisconnect 

Destroys a connection to the Environment manager and all associated variables. 
Call: 

Function EnvDisconnect( 

ServPort : Port) 
: GeneralReturn 

Parameters: 
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ServPort-Tpon designating connection. The port is deallocated. 

Results: 

Success 
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3 The I/O System 

3.1 Introduction 

The 10 (input/output) servers provide processes with the interface to access the 10 devices on a PERQ 
workstation. A standard interface to all the servers presents a common mechanism for acquiring use of the 
device that the given server manages, for making 10 requests to the server for using that device, and finally 
for relinquishing use of that device. For most of the 10 devices the servers permit processes to manipulate 
the device at the lowest level of functionality (i.e., the actual hardware registers). This feature is provided by 
supplying a fairly open-ended definition for the parameters to the main 10 request routine. It is felt that this 
type of control can best provide the flexibility needed by processes to make the device meet the needs of 
their particular applications. This does, however, place greater responsibility upon you to program the 
operation of the device correctly and efficiently. 

The primary role of the server then is to manage the actual details of device interaction (including the 
necessary physical memory requirements), to provide a convenient means for processes to perform 10 
operations, to handle the allocation and deallocation of the device, and to attempt to ensure the integrity of 
the device by restricting certain operations and recovering the device when it appears to be hung. 

Each 10 server registers itself with its local Name Server using a Name/Port pair. The Name part of the 
registration includes the name of the local machine and thus identifies the server (and the corresponding^ 
device) with the machine. Thus a process which desires access to a device on a remote machine can expect 
to receive a port to that remote device server when the local Name Server broadcasts the request for the 
Name over the network. 

3.2 Devices 

The 10 system provides access to all the 10 devices except the disk and network. There is one device server 
for each of the supported 10 devices. The supported 10 devices are: 

1. Floppy GPIB RS232A RS232B (PERQ2 workstation only) Speech 

These devices are currently supported by a Z80 microprocessor in the PERQ which acts as an 10 processor. 

'ML 

There is a single set of standard interface routines that provides you with access to all of the device servers. 
The way in which you select to which device server your request is being directed is to specify the 
appropriate port associated with that device server as the first parameter of one of the standard interface 
routines. Each device server has a special port registered with the Name Server that provides this unique 
access to the associated device server. The standard interface routines are found in IOUserPas in LibPascal, 
and 10 system definitions for various types used in the parameters for the routines are found in IODefsPas 
in LibPascal. 

33 Basic Routines 
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The user interface to an 10 Server is provided through a small set of standard routines: 
1) Procedure InitIO(RPort; Port ); 



2) Function IO.Version( 

ServPort : ServerNamePort 
): String; 



3) Function OpenIO( 

ServPort : ServerNamePort; 
Var IOPort : ServerlOPort; 
UserPort : UserEventPort 
): GeneralReturn; . 

4) Function CloseIO( 

IOPort : ServerlOPort 
): GeneralReturn; 



5) Function SyncIO( 

IOPort : ServerlOPort; 

Command : IOCommand; 

CmdBlk : Pointer; 

CmdBlk.Cnt : Long; 
Var DataBuf : Pointer; 
Var DataBuf Cnt : Long; 

DataTransferCnt : Long; 

TimeOut : Long; 
Var Status : IOStatusBlk 

): GeneralReturn; 

These routines are discussed in Sections 2.10. 

There are two other routines that will be implemented in a future release of Accent: 

a) Procedure AsyncIO( 

IOPort : ServerlOPort; 
Command : IOCommand; 
CmdBlk : Pointer; 
CmdBlk.Cnt : Long; 
DataBuf : Pointer; 
DataBuf Cnt : Long; 
DataTransferCnt : Long; 
TimeOut : Long 

); 
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b) Function Event( 
EventMsg : Msg; 
Var EvcntType : IOEvent; 
Var DataBuf : Pointer; 
Var DataBuf Cnt : Long; 
Var Status : IOStatusBlk 
): GcncralReturn; 

Except for 1) and b), each of these is actually a remote procedure call to a server and is implemented by 
sending a message to and receiving a reply from the server in order to accomplish the requested operation. 
The message passing interface is provided by modules created by the Matchmaker utility. 

3.4 Modes of Interaction 

Two modes of interaction - Synchronous and Asynchronous - are available for accessing a server to perform 
10 operations. The terms Synchronous and Asynchronous, as used here, do not imply anything about the 
type of data that the device is transferring (e.g., for RS232, it says nothing about whether the data is Bisync 
or Async). Synchronous and Asynchronous here refer to the style of user interaction with the server. 

In the Synchronous mode, the user process makes 10 requests through the SyncIO call. The user process is 
then blocked waiting for the reply message holding the results of the operation. This mode is useful if you 
do not want to deal with the details of the message passing system, since the Matchmaker generated 
interface modules handle the packing, sending, receiving, and unpacking of the messages implementing the 
remote procedure call. The Synchronous mode is also useful when the user process does want to block itself 
until a certain operation has been performed. 

The Asynchronous mode provides a means to queue 10 requests, using the AsyncIO call, without being 
blocked. This permits the user process to continue with other processing while the 10 operation is being 
performed. You are permitted to queue up more than one 10 request with the actual queue size limited by 
the particular server and the available message backlog limit on the server's port. When the server has 
completed a requested operation, it sends the results to you in a message as an asynchronous event which 
you must handle. Obviously, this now requires you to deal with the message system by doing an explicit 
Receive in order to obtain the event Upon receiving an event message, you can then call the Event routine 
which simply unpacks the message and fills in the parameters of the Event call according to the message 
content. (Thus you do not need to know about the details of IPC message formats.) Currently the 
Asynchronous interface is not implemented. 

3.5 Function of Basic Routines 

This section discusses in more detail the standard routines and their parameters. 

Except for the Initio and Event routines, the first parameter to each of the basic routines is a port which is 
created and owned by the pariktiiar server and* tha^, kicniifics the device server to which the user's request 
is directed. Each server owns two important ports - a ServerNamePort and a ServerlOPort - which provide 
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the access to users. The ScrverNamePort is registered with the Name Server and associated with a unique 
string name identifying the particular server. 

The current existing 10 servers are registered as: 

"[MachincNamelGPIBScrver" 

"[MachincName]FloppyScrver" 

"[MachincName]RS232AServer" 

"[MachincName]RS232BServer" 

"[MachineName]SpeechServer" 

where MachineName is the name of the machine upon which the device resides. This provides the means 
to access the devices on other machines across the network as well as local access. 

User programs acquire send access to a ServerNamcPort through a Lookup call to the NameServer. The 
ServerNamePort can only be used in the call to open the device or within the I0_ Version call. The server 
grants access to the device to the OpenIO caller by returning its ServerlOPort. The ServerlOPort is then 
used as the first parameter in all other calls to the server. Some servers (e.g., the Z80 supported device 
servers) may grant exclusive use of the device and not permit it to be opened again until it has been closed; 
other servers may permit multiple access. 

The Initio call is not directed to the server. The Initio procedure is created by Matchmaker and is part of 
the Matchmaker generated user interface module that implements (using the message system) the remote 
procedure calls. The user calls Initio with the parameter ReplyPort which is a port in the user's space and. 
to which the server is given send access for those remote calls (10_ Version, OpenIO, CloselO, and SyncIO) 
that are implemented with a message send followed by an explicit receive. If the ReplyPort equals NullPort 
in the user call, then Initio will allocate a port in the user's space for the reply messages for remote calls. 
The user must call Initio just once and before the first actual remote call (which should be OpenIO) to a 
server. 

The last parameter in the OpenIO call is the UserEventPorL This is a port owned by the user and to which 
the server will send asynchronous event messages. If the user specifies NullPort for the UserEventPort in his 
call to OpenIO, then the Asynchronous interface will not be enabled. This means that the server will ignore 
calls to AsyncIO and will not pass any other asynchronous events to the user. For now, the user should 
specify NullPort as the UserEventPort since the AsyncIO interface is not implemented. 

The parameters for the actual 10 calls are fairly straightforward. The CmdBlk, for instance, is a generic 
pointer to which the user can recast his own device specific command block pointer. See IODefs.Pas for the 
definition of this device specific command block, IOCmdBlk. CmdBlk_Cnt indicates the number of 
command bytes to which CmdBlk points. The CmdBlk is required to have a long integer occupying its first 
2 words which can be set by the user to provide an ID tag for the 10 command request. This tag is then 
copied into the first 2 words of the Status block when the response to the 10 request is made to the user. 
The ID tag is mostly useful for matching up server responses to 10 requests made through AsyncIO. The 
remainder of the CmdBlk is completely device specific. DataBuf points to a buffer for data transfers and 
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DataBuf_Cnt is the size of the buffer in bytes. The number of data bytes to transfer is indicated by 
DataTransferCnt. 

DataTransferCnt is not a redundant parameter. DataBuf Cnt is only used as an indicator of how many bytes 
pointed to by DataBuf are actually transmitted to/from the server in the message associated with the remote 
procedure call. Thus, for example, in a SyncIO call to read N data bytes, DataBuf should be set to Nil, 
DataBuf Cnt should be 0, and DataTransferCnt should be N when the user invokes the remote procedure. 
Upon return from SyncIO and assuming the server successfully carried out the request, DataBuf will point 
to a buffer holding the N bytes of data. This buffer will have actually been created by the kernel when it 
handles the receipt of the server generated response message to the remote call for SyncIO. The kernel 
maps the data pointed to in the response message into the user's address space and ultimately *the 
Matchmaker generated interface module will set DataBuf to point to that piece of memory. 

TimeOut, when applicable to a given command, indicates how long to wait for the command to complete 
before giving up on it. In most cases, a value of -1 means to not wait, zero means to wait indefinitely, and a 
positive value means to wait that many clock ticks where a tick is approximately 1 microsecond. The Status 
block holds information about the success or failure of the 10 command along with any available device 
status bytes. In the event of failure, the information in the Status block may also show how much of the 
command was performed before failure occurred. The set of IOCommands available will include those like 
IORead, IOWrite, IOReset, IOSense, etc., that are generally applicable to most devices as well as some that 
are device specific. Commands include those for data transfer and control, those for device control and 
configuration, and simple directives to the server. 



3.6 Example of SyncIO for GPIB 

In this section the service provided through the SyncIO call, along with a description of the parameters, is 
presented in the context of a specific example. Full definitions for new types are provided in an IODefs 
module found in Section 4. For GPIB the call and parameters are: 



SyncI0( IOPort 

Command 

CmdBlk 

CmdBlk_Cnt 
Var DataBuf 
Var DataBuf_Cnt 

DataTransferCnt 

TimeOut 
Var Status 
): General Return ; 



IOPort 



Command 



ServerlOPort ; 

IOCommand; 

Pointer; 

Long; 

Pointer; 

Long; 

Long; 

Long; 

IOStatusBlk 



As previously mentioned, this is the GPIB server port returned to the user upon 
successfully executing the OpenIO call. 

This is the user requested 10 command. Valid commands for GPIB are: 



IOSense 
IODevRead 



IORead 
IOReset 
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CmdBlk 

CmdBlkCnt 
DataBuf 

DataBufCnt 

DataTransferCnt 

TimeOut 



Status 



IOWrite 

IOWriteEOI 

IOFlushlnput 

IOReadHiVol 

IOWriteHiVol 



IODevWrite 
IOWriteRegisters 
IOSetBufferSize 
IOFlushOutput 



Each command will be discussed after presenting the rest of the parameters. 

This points to a record holding the CmdIDTag as well as device specific 
command bytes that are required for the command. The user's pointer to his 
IOCmdBlk for GPIB should be recast to a generic pointer. The definition for 
CmdBlk is given in Section 4. 

The number of valid bytes in the CmdBlk. This is always at least 4 to account for 
the CmdIDTag. 

This points to a buffer for the data which is to be sent or received. It is only used 
with the IORead, IOWrite, IOReadHiVol, IOWriteHiVol, and IODevWrite 
commands. 

The number of data bytes held in the buffer pointed to by DataBuf. 

The number of bytes to read/ write to/from the data buffer. 

The maximum number of clock ticks to wait before giving up on the command. 
A TimeOut value that is zero means to wait indefinitely. A TimeOut value of -1 
means to not wait at all for some commands (e.g. IORead to get data from the 
ring buffer) and means to wait indefinitely for other commands (i.e., where to 
not wait would make no sense). A positive TimeOut value means to wait that 
many clock ticks for the 10 operation to complete. A clock tick is approximately 
1 microsecond. For some commands, the TimeOut is irrelevant and is ignored. 
In some cases, when a command times out, the server will issue a device reset 
automatically. This is done for those commands for which a message is sent to 
the Z80. Since the Z80 always gives an ACK/NAK for each command message, 
a time out would indicate that the device is hung. The only command that can 
free the device for subsequent commands is device reset 

This shows the success or failure of the Command and, in either case, indicates 
how much of the command was performed. Also included is device status from 
the most recently issued IOSense command since the last device reset was issued. 
Obviously, the device status could be empty. Status will be defined by 
IOStatusBlk, IOSenseStatusBlk, and GPIBSenscStatus (see the definitions in 
Section 4). In the IOStatusBlk, HardStatus is status information provided by the 
device for the given Command. For IORead, for example, it is the error byte 
that is supplied with each character in the input ring buffer. SoftStatus is 
supplied by the server and provides a logical indication of the Command 
completion status. A list of the values used for SoftStatus is exported by the 
IODefs module. IOSuccess is the value returned in SoftStatus when the 
Command is successful. When command bytes are present, 
CmdBytesTransferrcd indicates how many of the bytes were actually transferred. 
DataBytesTransferred serves a similar function when the Command involves 
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data transfer. DcviceStatus for GPIB indicates the last available status from the 
internal registers of the TMS 9914 GPIB Controller chip which provides the 
interface to the GPIB. Refer to the Texas Instruments "TMS59914 GPIB 
Controller Data Manual" for a detailed description of this chip. 

3.7 Commands for GPIB 

In a number of the commands, the Z80 will wait until the data in the Z80's GPIB output ring buffer has 
been transmitted over the GPIB bus before actually initiating the command. Since some commands seize 
control and/or reconfigure the bus, it is necessary for the Z80 to wait until its GPIB output buffer has been 
drained before initiating those commands. This ensures the integrity of previous IO Write commands which 
have sent output data for GPIB. 

The standard TimeOut mechanism used for most commands is: 
TimeOut < = 0 means wait indefinitely 

TimeOut > 0 means wait TimeOut clock ticks 
and commands that do time out are followed immediately by a server issued device reset. 
SoftStatus is returned for each command and indicates success or the reason for failure. A list of SoftStatus 
codes with their meanings can be found in the IODefs module. A Command whose parameters are in error 
will be rejected and SoftStatus will indicate why. These types of errors will not be listed in the discussions » 
below. Assuming no parameter errors, the standard values for SoftStatus for most GPIB commands will be: 

IOSuccess Command completed successfully. 

IOTimeOut Command did not complete within the TimeOut period. 

IOUndefmedError Command was NAKed by the Z80. 

1. IOSense provides 10 bytes of status information from the Z80. Upon return, DeviceStatus in 
Status holds the count and the status bytes. The first 6 status bytes represent the register values in 
the TMS 9914 GPIB Controller chip at the time of the last Z80 GPIB interrupt and the remaining 
4 bytes show values current with the issued IOSense. (These are shown in the GPIBSenseStatus 
record in Section 4.) Note that current values for IntStatO and IntStatl cannot be obtained since 
reading those registers dismisses the interrupts that the bit maps in those registers represent. (See 
TMS 9914 Data Book for more details.) The server also maintains a copy of these 10 status bytes 
and copies them into the DeviceStatus field of Status for subsequent IOCommands. The server 
will always zero its copy of DeviceStatus after a device reset TimeOut for IOSense is standard. 
SoftStatus will be lOSucess, IOTimeOut, or IOUndefinedError. 

2. IOReset puts the GPIB Controller into the idle state by issuing a device reset for GPIB to the 
Z80. This clears the Z80's GPIB input and output buffers (any data is discarded) and puts the 
TMS 9914 into the idle state by performing a Software Reset aux command. The TMS 9914 
interrupt mode is reset for Data In and Data Out interrupts only, the Hdfa/Hdfe aux commands 
are disabled (in case they were previously set), and any data holdoff is released using Rhdf aux 
command. The PERQ workstation's GPIB input ring buffer is not affected. This command is also 
issued implicitly by the server for some of the other commands when they time out. TimeOut for 
IOReset is ignored since the device reset should never fail. 
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3. IOWritcRcgistcrs is used to program the TMS 9914 registers. CmdBlk points to the user's 
IOCmdBlk which, for IOWritcRegisters, contains an array of GPIBWritcRegister elements. Each 
GPIBWriteRegister is a pair of bytes where the first byte indicates the TMS 9914 register and the 
second byte is the value to be written. CmdBlk_Cnt indicates the total number of bytes and, thus, 
must be even. TimeOut and SoftStatus are standard. CmdBytesTransfcrred shows the total 
number of bytes transferered. 

4. IOFlushlnput is used to suspend GPIB bus activity and extract all remaining GPIB input data 
held in the Z80. This is done by issuing a Tea aux command to the GPIB Controller chip to 
suspend bus activity and sending all data accumulated in the Z80 GPIB input ring buffer to the 
PERQ workstation. In addition, any byte that is being held in the controller chip's Data In 
register is removed and also sent to the PERQ workstation. All data returned is deposited in the 
workstation's GPIB input ring buffer and can be obtained by the user with the IORead 
command. Note that the Tea aux command is not issued by the Z80 until the Z80's GPIB output 
buffer has been drained. TimeOut and SoftStatus are standard. 

5. IOFlushOutput flushes the Z80's GPIB output data ring buffer by waiting until all the data has 
been drained from the buffer. TimeOut and SoftStatus are standard. 

6. IORead is used to extract data from the PERQ workstation's GPIB input ring buffer. This does 
not require any interaction with the Z80 and, thus, a time out does not result in a device reset. 
When the user makes the remote call, DataBuf should be Nil, DataBuf_Cnt 0, and 
DataTransferCnt should indicate the number of bytes to read. Upon return from the call, 
DataBuf will have been set to point to the buffer holding the data sent by the server (and may be 
Nil). Each character in the PERQ workstation input ring buffer has a status byte (the value of 
IntStatO at the time of the Data In interrupt) associated with it. The server extracts characters and 
puts them into the DataBuf until either the DataTransferCnt is satisfied, a character's status byte 
shows an error, or no characters remain and the TimeOut expires. DataBytesTransferred is set to 
the number of characters returned in the DataBuf. SoftStatus is IOSuccess if the command 
succeeds completely. IONoDataFound is returned if no characters were found and the TimeOut 
expires. IOTimeOut is returned if the requested DataTransferCnt was not satisfied and the 
TimeOut expired. If the server finds a character with its status byte showing an error, it 
terminates further reading, puts the character into the DataBuf, sets HardStatus with the 
character's status byte, and sets SoftStatus to the appropriate error (IOCircBufOverflow or 
IOEndOflnput). For TimeOut, a value of 0 means wait indefinitely, -1 means don't wait, and > 0 
means the obvious. 

7. IOWrite sends data to the Z80 to be transmitted by the GPIB controller chip using Data Out 
interrupts. The Z80 buffers the data and sends an ACK when it has room in its buffer for another 
packet (i.e., 12 bytes is the most that can be sent in a single data packet) of data from the PERQ 
workstation. The server handles the user's IOWrite command by packaging the user's data 
pointed to by DataBuf into 12-byte packets and sending them to the Z80 as indicated above. 
(Obviously, IOWrite will be optimal when the DataBuf Cnt is a multiple of 12.) Thus the actual 
transmission of the last of the data bytes onto the GPIB bus can only be verified by the user 
following up with an IOFlushOutput command or some other command that waits until the Z80 
GPIB output buffer has been drained. TimeOut and SoftStatus are standard. 
DataBytesTransferred will indicate how many bytes were actually sent to the Z80 for 
transmission. 
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8. IOWritcEOI is the same as IOWrite except that the last data byte will be sent with the GPIB bus 
EOI line set The user must take care not to send more output data until the Z80 GPIB output 
buffer drains-otherwise, EOI may be set on the wrong byte. Draining of the buffer can be verified 
explicitly with IOFlushOutput or implicitly with one of the other commands. 

9. IOSetBufferSize is used to set the size of the physical buffer that is used for the IOReadHiVol 
and IOWriteHiVol commands. The default size is set to 1024 bytes when the device is allocated 
by the server in the OpenIO call. CmdBlk_Cnt should be 8 for this command. 

10. IOReadHiVol reads data from the GPIB using a DMA channel and thus provides a high transfer 
rate. As with IORead, DataBuf is Nil and DataBuf Cnt is 0 when the user makes the remote call 
and are set appropriately upon return. DataTransferCnt must be greater than 1 (since the Z80 
DMA cannot handle a byte count of 1). TimeOut and SoftStatus are standard. 
DataBytesTransferred indicates the number of bytes actually read. IOReadHiVol may be 
programmed to terminate early if EOI is raised by the sending device. When this feature is 
enabled and occurs, a completion of IOEndoflnput is returned for SoftStatus and 
DataBytesTransferred must be checked to determine the amount of data actually received. 

11. IOWriteHiVol writes data to the GPIB using a DMA channel. DataBuf points to a buffer holding 
DataBuf Cnt bytes. DataTransferCnt has the same restriction as for IOReadHiVol. TimeOut and 
SoftStatus are standard. DataBytesTransferred indicates the number of bytes actually written to 
GPIB and only needs to be checked when SoftStatus is not IOSuccess. The Z80 will wait for the 
Z80 GPIB output data ring buffer to drain before starting the HiVol operation. 

12. IODevRead and IODevWrite are somewhat complex commands that, in their simplest form, can 
be used just to configure the GPIB bus to change the Talker/Listener device on the bus. The 
CmdBlk points to a record containing the CmdIDTag followed by a GPIBDevCmdBlk. See 
Section 4 for the definition of GPIBDevCmdBlk. 

By setting all fields in GPIBDevCmdBlk to 0 or false except the PrimAddr and SecAddr, IODevRead 
would simply configure the bus with the device in PrimAddr and SecAddr as the new Talker; IODevWrite 
would configure a new Listener. If the SecAddr is not used, it should be set to 255. These commands are 
useful since they reduce a commonly used sequence of IOWriteRegister and IOWrite commands to a single 
command. They can also be used to configure the bus and set up the GPIB controller chip's interrupt mask 
registers appropriately for HiVol Read/Write commands. The basic algorithms for DevRead and Dev Write 
are given at the end of this section. 

For IODevRead, CmdBlkCnt should be 10. If ReadCount in GPIBDevCmdBlk is non-zero, the Z80 will 
wait until ReadCount bytes have been read (using Data In interrupts) from the configured GPIB Talker 
device and the Z80 will then hold off further input using the Hdfa aux command. As the data accumulates 
in the Z80, it is sent up to the PERQ workstation's GPIB input ring buffer. The Z80 returns (and thus the 
IODevRead completes) only after the requested number of bytes have been read and sent to the PERQ 
workstation. To obtain the data, the user must subsequently use the IORead command (i.e., for 
IODevRead, DataBuf is NIL and DataBuf Cnt is 0). 

For IODevWrite CmdBlk_Cnt should be 9. DataBuf points to DataBuf Cnt bytes of data to be transmitted 
on GPIB using Data Out interrupts. As with the IOWrite command, the data is shipped to the Z80 in 
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packets. (In terms of efficiency, note that the first packet holds the 5 byte GPIBDevCmdBlk plus only 7 data 
bytes.) 

For both IODevRead and IODevWrite, TimeOut and SoftStatus are standard. CmdBytesTransferred 
should be the same as CmdBlk_Cnt. DataBytesTransferrcd is valid only for IODevWrite and indicates the 
number of data bytes actually sent to the Z80 for transmission. 

The Z80 will wait before initiating the DevRead and DevWrite commands until the Z80 GPIB output ring 
buffer has drained. The basic algorithm for each command is then given below using the following 
definitions: 

AuxReg -- 9914 Auxiliary Command Register 
DataOut - 9914 Data Out Register 
Dataln - 9914 Data In Register 
MaskO - 9914 Interrupt Mask Register 0 
Maskl - 9914 Interrupt Mask Register 1 

DevWrite : 

With GPIBDevCmdBlk, GPIBDevCmdBl k. Options do 

begin 

AuxReg := Tea; 
AuxReg := Ton, off; 
AuxReg := Lon, off; 

If SetlntOMask then MaskO := IntOMask; 
If SetlntlMask then Maskl := IntlMask; 
If not OmitBusConf ig then 
begin 

DataOut := Unt; 

If not OmitUnlisten then DataOut := Unl; 
If (0 <= PrimAddr) and (PrimAddr <= 30) then 
begin 

DataOut := Mia + PrimAddr; 
If (0 <= SecAddr) and (SecAddr <= 31) then 
DataOut : = Msa + SecAddr; 

end; 

{ Note: We load the DataOut with the first } 
{ interface command (Unt) and the rest } 

{ are sent using Bus Out interrupts. } 

end; 

AuxReg := Ton, oh; 

If not OmitGoToStandby then AuxReg : s Gts; 
{Now handle the data bytes } 
If DataTransf erCnt does not equal 0 then 
begin 

DataOut := first data byte; 

{ Remaining data bytes are transmitted using } 
{ Bus Out interrupts } 
If ForceEOI then last data byte is sent with EOI; 
If WaitOnData then 



27 Aug 84 



Servcrs-25 



wait till all data sent before returning 
el se 

return without waiting; 

end; 
end { with }; 

DevRead : 

With GPIBDevCmdBl k, GPIBDevCmdBl k . Opt ions do 
begin 

AuxReg := Tea; 
AuxReg := Ton, off; 
AuxReg := Lon, off; 

If not Omi tBusConf ig then clear Dataln; 
If SetlntOMask then MaskO = IntOMask; 
If SetlntlMask then Maskl := IntlMask; 
If not OmitBusConf ig then 
begin 

DataOut := Unt; 

If not OmitUnl isten then DataOut := Unl; 
If (0 <= PrimAddr) and (PrimAddr <= 30) then 
begin 

DataOut :- Mta + PrimAddr; 
If (0 <= SecAddr) and (SecAddr <= 31) then 
DataOut := Msa + SecAddr; 

end; 

{ Note: We load the DataOut with the first interface } 
{ command (Unt) and the rest are sent using } 

{ Bus Out interrupts. } 

end; 

if HoldOffOnEOI then 

AuxReg := Hdfe, on 
else 

AuxReg := Hdfe, off; 
AuxReg := Hdfa, off; 

AuxReg := Rhdf; {Release any previous holdoff } 

AuxReg := Lon, on; 
AuxReg := Gts; 
If ReadCount <> 0 then « 
begin 

Wait until we have input ReadCount data bytes using 
Bus In interrupts and issue 

AuxReg Hdfa, on before the last byte is input, 
end 

end { with }; 
3.8 Commands for RS232, Speech and Floppy 

The valid SyncIO commands for the other servers will be discussed here. The description of the parameters 
to SyncIO is essentially the same as that given for GPIB in Section 2.4. Also, the description of th 
commands for GPIB in Section 2.5 is applicable except for the differences noted below for each device. The 
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timeout mechanism, use of the status block, and the delay waiting for the device's output ring buffer to 
drain before initiating certain commands is similar to the case for GPIB. 

3.8.1 RS232A 

The valid commands for RS232A are: 



IOSense 

IOReset 

IOFlushlnput 

IOFlushOutput 

IOSetBaud 

IOWritcRcgisters 

IOSense 



IOReset 



IOFlushlnput 



IOSetBaud 



IORead 



IOReadHiVol 
IOWriteRegisters 



IORead 

IOWrite 

IOSetBufferSize 

IOReadHiVol 

IOWriteHiVol 

Only 2 bytes of status information are held in the DeviceStatus record. These 
correspond to the last available values obtained for the ReadRegisters 0 and 1 of 
the Serial 10 (SIO) chip which implements the RS232 interface. 

This configures the RS232A channel to handle 9600 baud, 8-bit asynchronous 
data using 1 1/2 stop bits and no parity. The Data Terminal Ready (DTR) and 
Request To Send (RTS) signals (RS232 pins 20 and 4) are turned on and the SIO 
chip is programmed with Auto Enables mode. Auto Enables means that the 
Clear To Send (CTS) and Data Carrier Detect (DCD) inputs (RS232 pins 5 and 
8) are used as the enable signals for the respective transmission and reception of 
RS232 data bytes. This means that CTS must be on before the SIO chip will 
transmit a byte. And the DCD signal must be on before the SIO chip will 
actually assemble data bytes from the incoming bit stream. 

This simply sends all accumulated data held in the Z80 RS232A input ring 
buffer to the PERQ where it is deposited in the PERQ's RS232A input ring 
buffer. 

This is used to modify the rate of the internal baud rate clock used for 
transmitting and receiving asynchronous RS232 data bytes in their bit-serial 
form. The baud rate codes to use are defined in IODefs.Pas and include a code 
(RSExt) for synchronous RS232 data where external clocks are used to 
synchronize the character bit stream. CmdBlk_Cnt should be 6 for IOSetBaud. 

Similar to the GPIB example except that the per character status byte is the 
status byte provided by the SIO chip that accompanies each input data byte 
assembled by the chip. This byte is the value of SIO ReadRegister 1 which 
shows such errors as parity, framing, and overrun for the given input data byte as 
well as the end of frame condition and residue codes for SDLC data. Thus the 
SoftStatus code returned for IORead will be one of IOSuccess, IOTimeOut, 
IONoDataFound, IOCircBufOverFlow, IOParityError, IOFramingError, or 
IOEndOfFrame. 

Similar to GPIB. Note, however, that this command is not very useful for RS232 
and that the EOI feature of GPIB is not present. 

Permits you to program all SIO except WriteRegisters 1 and 2. These 2 registers 
are used to control the interrupt modes of the SIO chip. Registers 6 and 7 are 



27 Aug 84 



Servcrs-27 



used to specify the sync characters used for synchronous RS232 data transfers. 
Bit definitions for the other 4 registers arc given in Figures 1 through 4. 



WRITE REGISTER 9 



07 OS OS 04 03 02 01 08 



9 


9 


8 


Register 


8 


9 


9 


1 


Register 


1 


9 


1 


9 


Register 


2 


9 


1 


1 


Register 


3 


1 


a 


a 


Register 


4 


1 


9 


l 


Register 


5 


1 


i 


9 


Register 


6 


1 


i 


1 


Register 


7 



Null Code 

Send Abort (SDLC) 

Reset Ext/Status Interrupts 

Channel Reset 

Enable Int On Next Rx Character 
Reset Txlnt Pending 
Error Reset 

Return from Int (CH-A only) 



Null Code 

Reset Rx CRC Checker 
Reset Tx CRC Generator 
Reset Tx Underrun/EOM Latch 



Figure 1. Write Register 0 Bit Functions 
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WRITE REGISTER 3 



D7 I OS 05 04 03 D2 01 08 



8 8 Rx 5 Bits/Character 

8 1 Rx 7 Bits/Character 

1 8 Rx S Bits/Character 

1 1 Rx 8 Bits/Character 



Rx Enable 



Sync Character Load Inhibit 



Address Search Mode (SOLO 



Rx CRC Enable 



Enter Hunt Phase 



Auto Enables 



Figure 2. Write Register 3 Bit Functions 
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WRITE REGISTER 4 



D7 | PS | 05 | 04 | 03 | 02 | 01 | D9 1 



Parity Enable 

Parity EvenUK Odd(0) 



0 Sync Modes Enable 

1 1 Stop Bit/Character 

0 1-1/2 Stop Bits/Character 

1 2 Stop Bits/Character 



9 8 Bit Sync Character 

1 1G Bit Sync Character 

0 SDLC flode (01111110 Flag) 

1 External Sync Mode 



0 XI Clock Mode 

1 X1S Clock Mode 

0 X32 Clock Mode 

1 X64 Clock Mode 



Figure 3. Write Register 4 Bit Functions 
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URITE REGISTER S 

1 D7 I 06 I D5 | 0+ | 03 I Of I Uj li* 



Rx CRC Enable 



RTS 



CRC1S (U. SDLC (9) 



Tx Enable 



Send Break 



Tx 5 Bits (or Less) /Character 
Tx ? Bits/Character 
Tx 6 Bits/Character 
Tx 8 Bits/Character 




Figure 4. Write Register 5 Bit Functions 
■me byte masks.used, for example, to program the chip for the default settings 
obtained by IOReset are: 
Register # Bvte Mask (in octal) 
0 030 

0 ioo 

4 110 
3 341 

5 352 

3 82 RS232B 

' ' . . f p«wr k the same as RS232A except that the IOSetBufferSize, IOReadHiVol, and 
The description of RS232B is the same as k^za j> PERQ1 workstations. 

IOWriteHiVol commands are not present. Note again that RS232B does not exist r 

3.8.3 Speech 

The valid commands for speech are: 

IOSense IOWrite 

IOReset IOSetBufferSize 

IOSctBaud IOWriteHiVol 
IOFlushOutput 
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The description of these is the same as for RS232A except as noted below. The speech data output is 
implemented using the same type of SIO chip as for RS232 but configured instead for synchronous 8-bit 
data transmission using a single sync character of 252 (octal) which is automatically transmitted at the start 
of data transfers. The default baud rate is set at 32 KHz. 

IOReset Configures the hardware for the default state described above and clears the 

speech output ring buffer. 

IOSetBaud Changes the baud rate for bit-serial transmission of speech data to the actual 

speech output hardware in the PERQ. The SpeechTxRate field in the CmdBlk is 
set to obtain the desired bit rate in the following manner: 

PERQ1: 

SpeechTxRate = 2.456 * 10t6 

16 * (Desired Baud Rate) 

PERQ2 

SpeechTxRate = 4 * 10t6 

Desired Baud Rate 

A SpeechTxRate of 5 for PERQ1 and 1 25 for PERQ2 will 
give a baud rate of approximately 32 KHz. Note also 
that PERQs that have a portrait/landscape electro- 
magnetic ranging tablet instead of a Summagraphics 
BitPad tablet have a further restriction. Since the 
electromagnetic ranging tablet shares the same baud 
rate clock with Speech, modifying the Speech baud 
rate may have unpredictable effects on the behavior 
of the tablet. You may have to unplug the tablet 
while your application runs, and you should restore 
the baud rate to 32KHz before your program terminates. 
This can easily be done by issuing the IOReset command. 

3.9 Floppy 

The valid commands for floppy are given in the table below, along with some other information that will be 
explained below. 
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Table 1. Valid Commands for Floppy 







Returns 


Returns 


10 Command 


CmdBlk Cnt 


Device Status 


Hard Status 


IOReset 


4 


failure 


on failure 


IOSense 


4 


on success 


no 


IOSenseDrive 


4 


on success 


no 


IOReadlD 


6 


on success 


no 


IOSetDensity 


5 


no 


no 


IORecalibrate 


4 


on failure 


on failure 


IOSeek 


7 


on failure 


on failure 


IOFormat 


8 


on failure 


on failure 




IORead 


8 


on 


failure 


on failure 








IOWrite 


8 


on 


failure 


on failure 







The parameters to SyncIO have a similar description as that for GPIB in Section 2.4 The main difference is 
in the Status parameter. For Floppy, the DeviceStatus record in the IOStatusBlk is only valid as indicated in 
the table above. From the table "on failure" that the command failed for reasons other than IOTimeOut, 
IOUndefinedError, or some parameter error. This means that the floppy controller hardware initiated the 
command but failed to complete it. The controller always provides status information at the termination of 
each command. These bytes are returned to you "on failure" as the DeviceStatus record which for floppy is 
a FloppyResultStatus record as defined in IODefs.Pas. Also, "on failure", HardStatus in Status will be 
assigned the first byte of the device status which is Status Register 0 from the controller and is represented 
in the FloppyResultStatus record as: 

Unit : Bit2 {always 0} 

Head : Bitl 

NotReady : Boolean 
EquipFault : Boolean 
SeekEnd : Boolean 
IntrCode : ( 00 - Normal 

01 - Abnormal 

10 - InvalidCmd 

11 - DriveRdyChange) 

DeviceStatus is also returned "on success" for those commands listed in the table whose function it is to 
explicitly extract status about the last floppy operation or current drive state. Also shown in the table is the 
CmdBlk_Cnt required for each of the floppy commands. From the definition of IOCmdBlk in IODefs.Pas, 
we see that the command bytes for the commands involving actual floppy IO include a device address 
specifying the Unit, Head, Cylinder, and Sector. The range of these parameters is: 

Unit - always 0 

Head -0...1 

Cylinder - 0 ... 76 

Sector - 1 ... 26 
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For read/write commands, the logical mapping of floppy sectors is done by first increasing the sector 
number, then the cylinder number, and lastly the head number. For IORcad and IOWritc, the starting 
address on the floppy is given in the CmdBlk and DataTransferCnt indicates how many bytes should be 
read/written. To satisfy the requested number of bytes, the server will continue to read/write consecutively 
numbered sectors and will continue, if necessary, by advancing to the next cylinder on the same side. When 
the last cylinder on side 0 is read/written, it switches to side 1 at cylinder 0 and sector 1 and continues until 
the byte count is satisfied. Thus the server will implicitly do seek operations in order to satisfy the 
DataTransferCnt If the DataTransferCnt given is greater than the number of bytes that could possibly be 
read/written from/to the floppy from the starting address to the end of the floppy, then the server will not 
attempt to start the command and will reject it with an error code of IONotEnoughData / 
IONotEnoughRoom. 

The other floppy commands are fairly straightforward. The IOFormat command is used to format all 26 
sectors of a single track designated by the address in the CmdBlk. You must also specify in the CmdBlk the 
default data pattern to be written into the formatted sectors of that track. DataBuf for IOFormat must point 
to a buffer holding 26 4-byte SectorlDs for each of the 26 consecutive sectors on the track. Each 4-byte 
SectorlD is given as: 



Byte 


Information 


Range 


1 


Cylinder 


n 7* 


2 


Head 


0...1 


3 


Sector 


1...26 


4 


SectorSizeCode 


0...1 



where a SectorSizeCode of 0 is used for single density with 128 bytes per sector and 1 is used for double 
density with 256 bytes per sector. The server does not check the 104 (26 x 4) byte buffer of SectorlDs for 
correctness. You can also perform hardware interleaving of floppy sectors by simply specifying the desired 
sector number in each SectorlD. Thus if the list of sector numbers specified in the 26 consecutive SectorlDs 
is given by 1, 14, 2, 15, 3, 16, . . ., 12, 25, 13, 26, then a hardware interleave factor of 2 is achieved on that 
track. The IORecalibrate command forces the floppy to seek to head 0 and cylinder 0. IOReset does a 
device reset followed by a recalibrate. The timeout mechanism for floppy is the same as that described for 
GPIB in Section 2.5. 

3.10 Definitions 

The following definintions can be found in the Module IODeft. 
const 

{ Define return values for 10 errors. 
IOBaseMsglD = 4000; 
IOSuccess = SURESS; 
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IOErr = IOBascMsglD; 

IOUndcfinedError = IOErr + 1; 
IOTimcOut = IOErr + 2; 

IODeviceNotFree = IOErr + 3; 
IOInvalidlOPort = IOErr + 4; 
IOBadUscrEventPort = IOErr + 5; 
IOBadPortRefercnce = IOErr + 6; 
IOIllcgalCommand = IOErr + 7; 
IOBadCmdBlkCount = IOErr + 8; 
IOBadDataByteCount = IOErr + 9; 
IOBadRegisterNumbcr = IOErr + 10; 
IONotEnoughRoom = IOErr + 11; 
IOBadBaudRate = IOErr + 12; 
IONoDataFound = IOErr + 13; 
IOOverRun = IOErr + 14; 

IOParityError = IOErr + 15; 
IOFramingError = IOErr + 16; 
IOCircBufOverFlow = IOErr + 17; 
IOEndOfFrame = IOErr + 18; 
IOEndOflnput = IOErr + 19; 
IOBadSectorNumber = IOErr + 20; 
IOBadCylinderNumber = IOErr + 21; 
IOBadHeadNumber = IOErr + 22; 
IOUndcterminedEquipFault = IOErr + 23; 
IODeviceNotReady = IOErr + 24; 
IOMissingDataAddrMark = IOErr + 25; 
IOMissingHeaderAddrMark = IOErr + 26; 
IODeviceNotWritable = IOErr + 27; 
IOSectorNotFound = IOErr + 28; 
IODataCRCError = IOErr + 29; 
IOHcaderCRCError = IOErr + 30; 
IOBadTrack = IOErr + 31; 

IOCylinderMisMatch = IOErr + 32; 
IODriveReadyChanged = IOErr + 33; 
IONotEnoughData = IOErr + 34; 
IOBadBufferSize = IOErr + 35; 

type 

ServerNamePort = Port; 
ServerlOPort = Port; 
UserEventPort = Port; 



IOCommand = (IOSense, IOReset, IOWriteRegisters, 
IOFlushlnput, IOFlushOutPut, IORead, 
IOWrite, IOWritcEOI, IOReadHiVol, 
IOWriteHiVol, IODevRead, IODevWrite, 



27 Aug 84 



Servers-35 



IOSetBaud, IOSctStream, IOSetAttention, 
IOAbort, IOSuspend, IOResume, 
IOSeek, IORecalibrate, IOFormat, 
IOReadlD, IOSenseDrive, IOSetDensity, 
IOSetBufferSize, IONullCmd); 

IOEvent = (IOReply, AsyncData, Attention, Distress, Acknowledge); 

pIOMessage = tlOMessage; 
IOMessage = record 
Head : Msg; 

Body : array[0..1023] of integer; 

{ Note: The size of the Body is dependent 
{ upon the maximum size of messages 
{ that are passed between the Client 
{ and Server, This size is determined 
{ by the number and type of the parameters 
{ in the remote calls, the IPC conventions 
{ for packing data in-line, and the added 
{ parameters in the message that MatchMaker 
•f inserts f or coded return values. 
{ The actual size needed f or 10 messages 
{ is 46 given current IPC conventions, 
{ MatchMaker requirements, and actual 
{ parameters f or the remote calls. Future 
{ changes to any of the above may require 
{ modif ying the size for the Body. Accent 
{ gurus say that 1024 is a reasonably safe 
{ maximum f or the time being and that we 
{ should just use that here. 

end; 

GPIBWriteRegister = packed record 

case RegNum: Bit8 { really 0..6 } of 
0: ( { To be defi ned later! } ); 
1: (RegVal : BitS) 
end; 

SIOWriteRegister = packed record 

case RegNum: BitS { really 0..7 } of 
0: ( { To be defi ned later! } ); 
1: (RegVal : Bit8) 
end; 

GPIBDevCmdHead = packed record 
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Options: packed record { Bitmap to select cmd actions } 
SetlntOMask : boolean; 
SetlntlMask : boolean; 
OmitBusConfi g : boolean; 
OmitUnListen : boolean; 
case boolean of 

true : ( { f or IODevRead cmd } 
HoldOff OnEOI : boolean; 
unused2 : Bit3 

); 

false: ( { for IODev Write cmd } 
OmitGoToStandby : boolean; 
WaitOnData : boolean; 
ForceEOI : boolean; 
unusedl : Bitl 

); 

end; 

IntOMask : Bit8; { Mask for 9914 Interrupt Reg 0 } 
IntlMask : Bit8; { Mask for 9914 Interrupt Reg 1 } 
PrimAddr : Bit8; { Primary Address of device } 
SecAddr : Bit8; { Secondary Address of device } 
case boolean of 
true: ({ for IODevRead } 
ReadCount : Bit8 

); 

false: ( { for IODevWrite } 
{ nothing } 

); 

end; 

DensityType = (SingleDensity, DoubleDensity); 

pIOCmdBlk = tlOCmdBlk; 
IOCmdBlk = packed record 
CmdIDTag: long; 
case integer {IODevice} of 
0: {No Device for generic access} 
(case integer of 
0: {Byte access} 
(CmdByte: packed array[0..0] of Bit8); 

1: {Word access} 
(CmdWord: packed array[0..0] of integer); 

2: {Register access} 
(WriteReg: packed array [stretch(0)..stretch(0)] of 
packed record 



27 Aug 84 



Servcrs-37 



RegNum: Bit8; 
RegVal: Bit8 
end) 

): 



1: {GPIB} 
(case IOCommand of 
IOSetAttention: { AsyncIO only } 
(GPIBEnableATN: boolean); 

IOSetStream: { AsyncIO only } 
(GPIBEnableStream: boolean; 
GPIBBlockingFactor: integer); 

IOSetBufFerSize: 
(GPIBBufFerSize: long); 

IOWriteRegisters: 
(GPIBWriteReg: packed array[stretch(0)..stretch(0)] 
of GPIBWriteRegister); 

IODevRead, IODevWrite: 
(GPIBDevCmdBlk: GPIBDevCmdHead) 

); 

2: {RS232A, RS232B} 
(case IOCommand of 
IOSetAttention: { AsyncIO only } 
(RS232EnableATN: boolean); 

IOSetStream: { AsyncIO only } 
(RS232EnableStream: boolean; 
RS232BlockingFactor: integer); 

IOSetBufFerSize: { RS232A only } 
(RS232BufferSize: long); 

IOSetBaud: 
(RS232TxBaud: Bit8; 
RS232RxBaud: Bit8); 

IOWriteRegisters: 
(RS232WriteReg: packed array[stretch(0)..stretch(0)] 
of SIOWriteRegister) 

): 
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3: {Speech} 
(case IOCommand of 
IOSctAttention: { AsyncIO only } 
(SpeechEnableATN: boolean); 

IOSetBufferSize: { SpeechA only } 
(SpecchBufferSize: long); 

IOSetBaud: 
(SpeechTxRate: integer); 

IOWriteRegisters: 
(Speech WriteReg: packed array[stretcn(0)..strctch(0)] 
of SIOWriteRegister) 

); 

4: {Floppy} 
(case IOCommand of 
IOSetAttention: { AsyncIO only } 
(FloppyEnableATN: boolean); 

IOSetDensity: 
(FloppyDensity: DensityType); 

IORead, IOWrite, IOFormat, IOSeek, IORecalibrate, 
IOReadlD, IOSenseDrive: 
(FloppyUnit : Bit8; 
FloppyHead : BitS; 
case IOCommand of 
IORead, IOWrite, IOFormat, IOSeek: 
(FloppyCylinder: Bit8; 
case IOCommand of 
IORead, IOWrite: 

(FloppySector: Bit8); 
IOFormat: 
(FloppyFmtData: Bit8) 

) 

) 

) 

end; 



GPIBSenseStatus = packed record { IOSense to GPIB provides } 
{ first 6 bytes arc status at time of last interrupt } 
IntStatO : Bit8; { Interrupt Status 0 } 
IntStatl : Bit8; { Interrupt Status 1 } 
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IntAddrStat : Bit8; { Address Status } 
IntBusStat : Bit8; { Bus Status} 
IntAddrSwch : Bit8; { Address Switch } 
IntCmdPass : Bit8; { Command Pass Through } 

{ next 4 bytes arc current status } 
CurAddrStat : Bit8; { Address Status (now) } 
CurBusStat : Bit8; { Bus Status (now) } 
CurAddrSwch : Bit8; { Address switch (now) } 
CurCmdPass : Bit8; { CurCmdPass (now) } 
end; 

SlOSenseStatus = packed record 

{ Read General Status - SIO Chip's Read Register #0 } 

RxCharAvailable : boolean; 

IntPending : boolean; 

TxBufferEmpty : boolean; 

DCD : boolean; 

SyncHunt : boolean; 

CTS : boolean; 

TransmitUnderRun : boolean; 

BreakAbort : boolean; 

{ Read Special Condition - SIO Chip's Read Register #1 } 
AllSent : boolean; 
Residue : Bit3; 
ParityError : boolean; 
RxOverRun : boolean; 
CrcFramingError : boolean; 
EndOfFrame : boolean; 
end; 

FloppyResultType = (NoStatus, {no status available} 

HeadChange, {status from Seek or Recalibrate} 
DriveSense, {status from SenseDrive} 
CmdResults {status from other drive cmds} 

); 

FloppyResultStatus = packed record 

{ Floppy device status is always returned as part } 
{ of the result phase of a cmd to the controller. } 
{ Z80 simply maintains a copy of the status results} 
{ for the last cmd. } 
StatusType: FloppyResultType; 
Unused : Bit6; 
case FloppyResultType of 
NoStatus: ({nothing}); 
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HeadChange, DriveSense, CmdResults: 
(Unit: Bit2; 
Head: Bitl; 

case FloppyResultType of 
DriveSense: 
(TwoSided : boolean; 
AtTrackO : boolean; 
DriveReady : boolean; 
WriteProtected: boolean; 
DriveFault : boolean 

); 

HeadChange, CmdResults: 
(NotReady : boolean; 
EquipFault: boolean; 
SeekEnd : boolean; 
IntrCode : (Normal, Abnormal, 

InvalidCmd, DriveRdyChange); 
case FloppyResultType of 
HeadChange: 

(PresentCylinder: Bit8); 
CmdResults: 

(NoAddrMark : boolean; 

NotWritable : boolean; 

NoData : boolean; 

Unusedl : Bitl; 

Overrun : boolean; 

DataError : boolean; 

Unused2 : Bitl; 

TrackEnd : boolean; 

NoDataAddrMark: boolean; 

BadTrack : boolean; 

ScanFail : boolean; 

ScanHit : boolean; 

WrongCylinder : boolean; 

DataCRCError : boolean; 

ControlMark : boolean; 

Unused3 : Bitl; 

CylinderlD : Bit8; 

HeadID : Bit8; 

SectorlD : Bit8; 

SectorSizeCode: Bit8 

) 

) 

) 

end; 

IOSenseStatusBlk = packed record 
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StatusCnt: Bit8; 
case integer {IODevice} of 
1: {GPIB} 

(GPIBStatus: GPIBSenseStatus); 
2: {RS232A, RS232B, Speech} 
(SlOStatus: SlOSenseStatus); 
3: {Floppy} 

(FloppyStatus: FloppyResultStatus); 
0: {otherwise} {for generic access } 
(case integer of 
1: (StatusByte: packed array[stretch(l)..stretch(l)] 
of Bit8); 

2: (StatusWord: packed array [stretch(l)..stretch(l)j 
of integer); 

3: (SByte : packed array[stretch(l)..stretch(12) 
]ofBit8) 

) 

end; 



lOStatusBlk = packed record 

CmdIDTag : long; 



HardStatus 



"6* 



SoftStatus : integer; 
CmdBytesTransf erred : long; 
DataBytesTransferred : long; 
DeviceStatus : IOSenseStatusBlk; 
end; 



const 
O 

{ Baud rate codes for RS232. 
0 



RSExt 

RS110 

RS150 

RS300 

RS600 

RS1200 

RS2400 

RS4800 

RS9600 

RS19200 



= 0 
= 1 
= 2 
= 3 
= 4 
= 5 
= 6 
= 7 



{only for RS232A} 



3.11 Routines 



The following Routines are from IOUser.pas. 
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Initio 

Initio is used to specify the port in the calling process's port space that will be used by the other interface 
routines in 10 User. Pas to accomplish the remote procedure calls to the 10 servers. The port specified serves as 
the reply port upon which the response from the server will be received This procedure should be called once 
and before any of the other routines in 10 User. Pas are used 

Call: 

Procedure InitIO(RPort: Port) 

Parameters: 

RPort- This is a port in your process's port space. If NullPort 

is specified, then Initio will create a new port. 

Most programs find it convenient to just specify NullPort. 

Results: 

None, 



IO Version 

This function returns a string which identifies the version number of the server. 
Call: 

Function IO.Version( 

ServPort : ServerNamePort) 
: String 

Parameters: 

ServPort-This is the port that identifies the IO server to which your request 
is being directed. It is the port that you obtain from the Name 
Server when you perform a Lookup to the Name Server for the desired 
IO server. 

Returns: 

The server's version number in string form. 

■ [■ IMIMIMi nm i » l M I«IBIM f lMIB IW IMIBIBI MI «l«I HI B I MI«l« IM i ai BI« i aiBIBi n iH I MI ■ 

OpenIO 

Open IO is used to acquire the right to use the device managed by the selected IO server. The server grants 
access to a process by returning a port which the process then uses in the other IO calls. Some servers grant 
exclusive use to a single process and thus OpenIO performed by other processes will be rejected until the 
current process relinquishes access with the CloselO call. OpenIO will always enable the Synchronous 
interface to the server and will only enable the Asynchronous interface if a UserEventPort is specified 
Currently, the Asynchronous interface is not implemented and thus NullPort should be used here. 
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Call: 

Function OpenIO( 

ServPort : ServerNamePort; 
Var IOPort : ServerlOPort; 
UserPort : UserEventPort ) 
: GeneralRetura 

Parameters: 

ServPort-This is the port that identifies the 10 server to which your request 
is being directed. It is the port that you obtain from the Name 
Server when you perform a LookUp to the Name Server for the desired 
10 server. 

lOPort-This is the port returned by the server 
(if the OpenIO request is 

granted) which the caller uses to make subsequent 10 requests. 

UserPort-This is the port upon which the calling 
process wishes to receive 

Asynchronous events. This port should be set to NullPort until the 
AsyncIO call is implemented. NullPort directs the server to not 
enable the Asynchronous interface. 

Results: 

IOSuccess-\f the request is granted. 

IODeviceNotFree-if an exclusive-use device is already allocated. 



CloselO 

CloselO is called when you are through using the device managed by the selected server. The specified 
ServerlOPort identifies to which server the CloselO is being directed 

Call: 

Function CloseIO( 

IOPort: ServerlOPort) 
: GeneralReturn 

Parameters: 

IOPort-This is a ServerlOPort that uniquely identifies the server to which 
the CloselO is directed. The port to use here is the ServerlOPort 
returned by the server in the OpenIO call. 

Results: 
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IOSuccess-if no errors; otherwise returns an 
identifying error code. 



SyncID 

SyncIO is the primary call to be used in performing actual 10 operations on the device managed by the 
selected 10 server. The specified ServerlOPort identifies the server to which the request is directed. The other 
parameters are specified according to the particular requirements for the device and the valid set of commands 
applicable to the device. These are discussed in more detail in other parts of this document and are also 
presented in the module IODefs.Pas. The server performs the operation and the SyncIO call returns whenever 
the operation completes or times out. A device dependent status block is returned which shows the degree of 
success in the completion of the operation. The set of 10 error codes as well as the status block definition can 
also be found in IODefs.Pas. In most cases the server will automatically issue a device reset when an operation 
times out. For calls that don't involve the return of data, the server will always set the DataBuf parameter to 
Nil. Thus you must be careful about the parameter you supply for DataBuf so that you don't lose your 
reference to a piece of memory inadvertently. 

Call: 

Function SyncIO( 

IOPort : ServerlOPort; 

Command : IOCommand; 

CmdBlk : Pointer; 

CmdBlk _Cnt : Long; 
Var DataBuf • : Pointer; 
Var DataBuf_Cnt : Long; 

DataTransferCnt : Long; 

TimeOut : Long; 
Var Status : IOStatusBlk) 
: GeneralRetura 

Parameters: 

IOPort-This is a ServerlOPort that uniquely identifies the server to which 
the CloselO is directed. The port to use here is the ServerlOPort 
returned by the server in the Open 10 call. 

Command-This is the IOCommand to perform. 

Cm dBlk-This is a pointer to the device specific command block. For most 
commands, you can treate a pointer to an IOCmdBlk and just recast 
CmdBlk to point to it. For other commands (like lOWriteRegisters) 
which have an arbitrary number of command bytes, you will need to 
create a large enough buffer to accommodate your command bytes and 
set CmdBlk to point to it. You may also want to treat your command 
buffer as an IOCmdBlk for purposes of using the record field names to 
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assign the command byte values. Note that the first two words of the 
command block are always treated as a CmdldTag by the server and will 
be copied into the status block prior to return. The CmdldTag is 
primarily useful in the AsyncIO interface to the server. 

CmdBlkCnt-Va\s is the number of command bytes pointed 
to by the CmdBlk parameters. 

DataBuf-Ta\s is the pointer to the data. For commands that read data from a 
device, DataBuf should be set to Nil before the call. Upon return, 
DataBuf will point to a buffer holding the data read. When you are 
through with the buffer pointed to by DataBuf, you should use the 
InvalidateMcmory call (see the document "Kernel Interface" in this 
manual) to deallocate the buffer. For commands that write data to a 
device, DataBuf will point to your buffer of data to output. Since 
the server will always set DataBuf to Nil prior to return for 
commands that don't return input data, you must take care here not to 
lose your pointer reference to the buffer used in the call. This is 
easily done by using a generic pointer variable for DataBuf that has 
also been set to point to your output buffer. 

rintnhiifr jif— Tliic ic thp nnmh^r nfl>ytf>c in the* hiiflRar ri'^ir!*"' 1 ^ TiptoniiF l^Vi* 1 
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read commands, this is the number of data bytes the server has 
returned to you. For read commands you should set DataBuf to Nil and 
DataBuf Cnt to 0 prior to the call. (This eliminates the overhead of 
passing useless data in the message to the server and prevents any 
potential invalid memory references.) For write commands, this is 
the number of bytes in your output buffer. 

DalaTransferCni-This is the number of bytes that you want to read/ write 
from/to the device. 

TimeOut-This is the number of microseconds that the server should wait for 
the operation to complete. A value of 0 means to wait indefinitely. 
A negative value means to not wait (when that makes sense) and 
otherwise has the same meaning as 0. 

Slatus-This is the completion status of the operation. Included here is the 
DeviceStatus which is device dependent and may hold the values of 
device status registers when they were last obtained from the device. 
The current values are explicitly obtained when the IOSense command is 
issued. 

Results: 

IOSuccess-\f the operation succeeds completely; otherwise returns 
an identifying error code. If the command fails, Status can also be 
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checked for more detailed error information as well as an indication 
of how much of the command succeeded. 
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4 Name Server 

4.1 Introduction 

The Name Server provides processes with the ability to establish communications using textual names. In 
general, a process registers a Name/Port pair with the NameServer. Other processes can then ask the Name 
Server if it has a registration for a specific name. 

If a name is not registered with the local Name Server, that Name Server will broadcast a request on the 
network. If the name is registered with some other Name Server on the network, that remote Name Server 
will reply with a Port. 

At the current time the Name Server is a portion of the Message Server Process. The Message Server is 
responsible for extending InterProcessCommunication (IPC) over the network. The fact that the Name 
Server and the Message Server are the same process is transparent to a client of the Name Server. 
Communication with the Name Server is through a Matchmaker-generated interface. The port that is used 
for communications with the Name Server is NameServerPort defined in PascallniLpas. 

4.2 Functions 

The following functions are from MsgNUser.pas. 

Checkln 

Checkln is used to register a Name/Port pair with the local Name Server. 
Call: 

Function Checkln( 

ServPort : Port; 
PortsName: string; 
Signature: Port; 
PortsID : Port) 
: GeneralReturn 

Parameters: 

ServPort-The port that is used to communicate with the Name Server. 
It is NameServerPort from PascallniL 

PortsName-The name to be registered. 

Signature-This is not currently implemented. Use NullPort for this 
parameter. 

PortsID-TciQ port that is, to be associated with PortsName. Clients of 

the Name Server who request a connection to PortsName will be given Send rights 

to PortsID. 
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Results: 

Success-Name was registered correctly. 



LookUp 

LookUp is used to obtain a port that is associated with a name. 
Call: 

Function LookUp( 

ServPort : Port; 
PortsName: string; 
varPortsID : Port) 
: GeneralReturn 

Parameters: 

ServPort-The port that is used to communicate with the Name Server. 
It is NameServerPort from Pascallnit. 

PortsName-The name to look for. 

PortsID-The port that is to be associated with PortsName.The caller 
of LookUp will be given send rights to PortsID. 

-The port PortsName was found and PortsID contains a port 
that can be used to communicate with it. 

-The port PortsName was not found. PortsID is not 
valid. 



Checkout 

Checkout is used to remove a Name/Port registration from the Name Server. 
Call: 

Function CheckOut( 

ServPort : Port; 
PortsName: string; 
Signature : Port ) 
: GeneralReturn 

Parameters: 

ServPort-Tha port that is used to communicate with the Name Server. 
It is NameServerPort from Pascallnit 
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PortsName-The name to be removed- 
PS = Signature 

-This is not currently implemented. Use NullPort for this 
parameter. 

-Name was removed 

-The client tried to remove a name that it did not 
register. 



MsgPortStatus 

MsgPortS talus returns Message Server internal information about a Port. This function is a system function 
and is not for users. 
Call: 

Function Checkln( 

ServPort : Port; 

PortsID : Port; 
var GlobalPort : long; 
var Owner : long; 
var SrcID : long; 
var SeqNum : long; 
var NetWaiting : boolean; 
var NumQueued : integer; 
var Blocked : boolean; 
var Locked : boolean; 
var RecvQueue : integer; 
var DataOff set : long; 
var InSrcID : long; 
varlnSeqNum :long) 
: GeneralReturn 
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5 The Network Server 

5.1 Introduction 

The Network Server (or NetServer) provides access to the Ethernet for all processes that are running on a 
given Perq. All access to the Ethernet is through the Network Server. The CMU 3MHz NetServer provides 
access to both the 3MHz and 10MHz Ethernets. On the 10MHz Ethernet it functions by encapsulating 
3MHz Ethernet packets within 10 MHz Ethernet packets. 

Note that this 3MHz network server is unique to CMU. At other sites a 10MHz NetServer is used by Perqs 
communicating solely on a 10 MHz Ethernet. See the PERQ Systems document, The Network Server, for 
more details. 

User access to the Network Server is through a Matchmaker-generated message interface. The Network 
Server user sees a set of procedure calls. These calls are translated by Matchmaker-generated code into 
messages that are then sent to the Network Server. The Network Server will act on the request and send a 
reply to the client. The reply messages are translated by Matchmaker-generated code into a format that is 
suitable for the user. (Because the netserver used to be called the EtherServer, the matchmaker interface to 
is is called EtherUser.) 

When a user process wishes to receive packets from the Ethernet, it informs the Network Server. The user 
provides the Network Server with the type of Ethernet packets that it wishes to receive. It also provides send 
rights to a port. When an Ethernet packet is received by the Network Server the Server checks to see if any 
of its users are interested in packets of that type. If so it will send the received packet to those users in an 
IPC message. To get the message cotaining a packet, the user does an IPC receive on the port that it 
previously provided to the Network Server to get the message that contains the packet. The user then uses 
Matchmaker-generated code to obtain the actual Ethernet packet from this IPC message. 

5.2 overview 

In order to provide both synchronous and asynchronous communication with the NetServer, the functions 
provided by this module are implmented with three subroutine call each. The Send and Parse calls are to be 
used (along with a user written Receive call) for asynchronous communication. The Wait calls are to be 
used for synchronous communication. The three types of routines have following implementation: 

Send<X> This routine sends off a request message to the NetServer. It usually takes a 

reply port as^well as parameters to the function, and returns the result of the 
send call. 

Parse<X> This routine parses a request response from the NetServer. It usually takes a 

message pointer as a parameter and returns the function results as its result, or in 
var parameters, depending on the number of output variables. 

Wait<X> This routine combines the above two routines for synchronous server 

communication. It will raise an exception if something goes wrong. The 
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exceptions are defined below. It should be pretty obvious what their arguments 
refer to. 

All the routines implicitly take the NetServer port as a parameter. This port is hidden withing the 
EtherUser module and is initialised when the routine InitEther is called. 

The netserver supports two types of packet format: raw 3Megabit ether packets, and pup packets. Thus 
there are parallel sets of calls depending on which packet format is desired. 

53 Initializing the interface 

The procedure InitEther must be called before other routines can be executed. 
Example: 

InitEther (NullPort, 0); 

5.4 Getting the Ethernet Address of the Machine 

The Network Server user must place the Ethernet address of the current machine into the Source field of 
the Ethernet packet header. The Network Server provides facilities to get the Ethernet address from the 
Ethernet hardware. The address that is returned is in a form that can be placed directly into an address field 
of an Ethernet header. The CMU MHz network server always returns a 3MHz address even thought the 
machine may be on the lOMhz ethernet. 

Example: 
VAR 

host : integer; 
BEGIN 

host := Wai tEtherAddress ; 
writeln ('My host = ', host:l); 

5.5 Sending an Ethernet Packet 

To send a packet on the Ethernet, the user must set the Ethernet packet header to contain the destination 
address, the correct source address and the packet type fields of the header. The packet can be sent using 
SendEtherPacket 

5.6 Connecting to an Ethernet Type 

To receive packets from the network, the user process must tell the Network Server that it wishes to receive 
packets of a specific Ethernet type on a user-provided port. The Ethernet type acts as a filter within the 
network server. It is possible to receive packets of more than one Ethernet type on a single port by making 
multiple calls to WaitEtherFilter with different filters but with the same port. 

Example: 



27 Aug 84 



Servers-52 



VAR 



filter 
retval 
ok 

myport 



integer; { Packet type } 

General Return ; 

boolean; 

port; 



BEGIN 

retval : = AllocatePort (KernelPort, myport, Def aul tBacklog) ; 
Write ('Filter number: *); 
Readln (filter); 

ok := WaitEtherFil ter (myPort, filter); 



5.7 Type Definitions 



The following definitions are from EtherTypes.pas. 

CONST { return codes from PerqE3, PerqElO, PorkE3 } 
IOEIOC = #0; { successful } 

IOETIM = # 1; {no packet is being returned from Ethcr3Receive } 

IOEPTL = #2; {a packet > WdCnt has been received } 

IOERNT = #3; { a packet < WordSize(EtherHeader) has been received } 

IOEBSE = #4; { WdCnt > E3BufferSize } 

IOEFUZ = #5; { packet length not integral number of words } 



TYPE 

EtherHeader = PACKED RECORD 
Src : 0..255; 
Dst :0..255; 
Typ : INTEGER; 
END; 



CONST 

MinEtherWords = WordSize(EtherHeader); 

MaxEtherWords = 748; { 750 words max data size on lOmhz net, but 2 
words are needed for the 3hmz encapsulation 
header on the lOmhz net. } 
{ 560 is the vax 3mhz limit (ENETPACKETSIZE)} 



TYPE 

pEtherPacket = tEtherPacket; 
EtherPacket = RECORD 

CASE Integer OF 

0:( 

Header : EtherHeader; 
DataWords : ARRAY[0 .. MaxEtherWords - 
WordSize(EtherHeader) - 1 
] OF INTEGER); 

1:( 
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Words : ARRAY[0 .. MaxEtherWords- 1] OF INTEGER ); 
2: ( 

LongHeader : EtherHeader; 

LongWords : ARRAY[0 .. (MaxEtherWords - 

WordSize(EtherHeader)) 

div2- 1] OF LONG); 

3:( 

ConfigHdr : EtherHeader; 
SkipC : integer; 
ConfigBytes : PACKED ARRAY 

[0 .. 2 *(MaxEtherWords - 
WordSize(EtherHeader) - 1)] 
OFBit8) 

END; 

CONST 

EtherTypEehoMe = #700; 
EtherTypIAmAnEcho = #701; 
EtherTyp3ConfigTest = #220; 
EtherTypPup = #1000; 
EtherTypConfigTest = #220; 

FwdCode = 2; 

RepiyCode = 1; 

TYPE 

PupLLong = RECORD 

CASE INTEGER OF 
1 : ( Lng : Long ); 
2 : ( Low : Integer; 

Hgh : Integer ) 
END; 

TYPE 

PupHLong = RECORD 

CASE INTEGER OF 
1 : ( Lng : Long ); 
2 : ( Hgh : Integer; 

Low : Integer); 
END; 



TYPE 

PupPort = PACKED RECORD 
CASE integer OF 
0:( 

Host: 0.. 255; 
Net :0.. 255; 
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Soc : PupHLong ); 
1:( 

All : PACKED ARRAY [0..5] OF Char ) 
END; 



TYPE 
PupHeader 



TYPE 
pPupData 
PupData 



Len 
Typ 
TC 
Id 
Dst 
Src 
END; 



PACKED RECORD 
: INTEGER; 
:0.. 255; 
: 0.. 255; 
: PupHLong; 
: PupPort; 
: PupPort 



= t PupData; 
= RECORD 
CASE INTEGER OF 

0 : (Chars : PACKED ARRAY[ 0..1043] OF CHAR); 
1 : (Bytes : PACKED ARRA Y[ 0..1043] OF 0..255); 

2 : (Words : PACKED ARRAY[ 0.. 521] OF INTEGER); 

3 : (HLongs : PACKED ARRAY[ 0.. 260] OF PupHLong); 

4 : (Ports : PACKED ARR AY[ 0.. 260] OF PupPort); 
END; 



CONST 

MinPup Words = WordSize(PupHeader)+l; 
MaxPup Words = 533; 

TYPE 

pPupPacket = tPupPacket; 
PupPacket = RECORD 

CASE INTEGER OF 

0 : ( Header : PupHeader; 
Data : PupData ); 

1 : ( ChkSums : ARRAY [0..532] OF Integer ) 

END; 



CONST 

PupCMUNet = #52; 
CONST 

PupError = #4; 

PupEFTPData = #30; 

PupEFTPAck = #31; 
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PupEFrPEnd = #32; 
PupEFTPBort = #33; 



CONST 

PupNameSocket = #4* #200000; { word- swapped longs} 
PupEFTPSocket = #20*#200000; 

TYPE 

MsgPacket = RECORD 

Head : Msg; 

TPacket :TypeType; 
END; 

MsgEtherPacket = RECORD 
Head : Msg; 

TPacket : TypeType; 
Packet : EtherPacket; 
END; 



MsgPupPacket = RECORD 
Head : Msg; 

TPacket : TypeType; 
Packet : PupPacket; 
END; 



CONST 

PacketBytes = 2 * WordSize(MsgPacket); 
EtherPacketBytes = 2 * WordSize(MsgEtherPacket); 
PupPacketBytes = 2 * WordSize(MsgPupPacket); 

CONST 

EtherlDBase = 800; 



IDGetEthcrAddress = EtherlDBase + 1; 
IDRGetEtherAddress = EtherlDBase + 101; 



IDSetEtherFilter = EtherlDBase + 2; 
IDRSetEtherFilter = EtherlDBase + 102; 



IDClrEtherFilter = EtherlDBase + 3; 
IDRClrEtherFilter = EtherlDBase + 103; 



IDSendEtherPacket = EtherlDBase + 4; 
IDRecvEtherPacket = EtherlDBase + 104; 



IDSetPupFilter = EtherlDBase + 5; 
IDRSetPupFUter = EtherlDBase + 105; 
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IDClrPupFilter = EtherlDBase + 6; 
IDRClrPupFilter = EtherlDBase + 106; 

IDSendPupPacket = EtherlDBase + 7; 
IDRecvPupPacket = EtherlDBase + 107; 

TYPE 

pMsgGetEtherAddrcss = tMsgGetEtherAddress; 
MsgGetEtherAddress = RECORD 
Head : Msg 
END; 

pMsgRGetEtherAddress = tMsgRGetEtherAddress; 
MsgRGetEtherAddress = RECORD 

Head : Msg; 

TEtherAddress : TypeType; 

EtherAddress : INTEGER 
END; 

pMsgSetEtherFilter = tMsgSetEtherFilter; 
MsgSetEtherFilter = RECORD 

Head : Msg; 

TTyp : TypeType; 

Typ : INTEGER; 

TProcessPort: TypeType; 

ProcessPort : Port 
END; 

pMsgRSetEtherFilter = tMsgRSetEtherFilter; 
MsgRSetEtherFilter = RECORD 

Head : Msg; 

TTyp : TypeType; 

Typ : INTEGER; 

TAnswer : TypeType; 

Answer : BOOLEAN 
END; 

pMsgClrEtherFilter = tMsgClrEtherFilter; 
MsgClrEtherFilter = RECORD 

Head : Msg; 

TTyp : TypeType; 

Typ : INTEGER; 

TProcessPort: TypeType; 

ProcessPort : Port 
END; 

pMsgRClrEtherFilter = tMsgRClrEtherFilter; 
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MsgRClrEtherFilter = RECORD 
Head : Msg; 
TTyp : TypeType; 
Typ : INTEGER; 
TAnswer : TypeType; 
Answer : BOOLEAN 
END; 

pMsgSendEtherPacket = tMsgSendEtherPacket; 
MsgSendEtherPacket = MsgEtherPacket; 

pMsgRecvEtherPacket = tMsgRecvEtherPacket; 
MsgRecvEtherPacket = MsgEtherPacket; 

pMsgSetPupFilter = tMsgSetPupFilter; 
MsgSetPupFilter = RECORD 

Head : Msg; 

TSocket : TypeType; 

Socket : Long; 

TProcessPort: TypeType; 

ProcessPort : Port 
END; 

pMsgRSetPupFilter = tMsgRSetPupFilter; 
MsgRSetPupFilter = RECORD 

Head : Msg; 

TSocket : TypeType; 

Socket : Long; 

TAnswer : TypeType; 

Answer : Boolean 
END; 

pMsgClrPupFilter = tMsgClrPupFilter; 
MsgClrPupFilter = RECORD 

Head : Msg; 

TSocket : TypeType; 

Socket : Long; 

TProcessPort: TypeType; 

ProcessPort : Port 
END; 

pMsgRClrPupFilter = TMsgRClrPupFilter; 
MsgRClrPupFilter = RECORD 

Head : Msg; 

TSocket : TypeType; 

Socket : Long; 

TAnswer : TypeType; 
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Answer : Boolean 
END; 

pMsgSendPupPacket = tMsgSendPupPacket; 
MsgSendPupPacket = MsgPupPacket; 

pMsgRecvPupPacket = tMsgRecvPupPacket; 
MsgRecvPupPacket = MsgPupPacket; 

5.8 Exported Exceptions 

Exception ESendFailed(Why: GeneralReturn); 
Exception EReceiveFailed(Why: GeneralReturn); 
Exception EBadReply; 

5.9 Common Parameters 

GeneralReturn The return code from the Send Kernel call. 

Listener The port to which to send the notification that a reply to this call has been 

received. 

MaxWait Maximum number of milleseconds to wait for a send to NetServer to complete. 

The value 0 means wait forever. 

MsgP A pointer to a specific type of message. 

Option Send option for the Send call. Specifies what to do if the server queue is full. 

Values are wait,dontwait, and reply. 

packet A pointer to a pup packet 

Reply Port to which reply to this message is to be sent 

Typ A filter specifying the types of ethernet packages that are to be listened for. The 

values for this parameter are exported by ethertypes.pas. 

socket The local part of a pup protocol EtherNet address. This acts as a filter for pup 

tranmission. 

5.10 Procedures 

The following procedures are found in EtherUser.pas. 

■ ■ ■■■IWIBIW m i«IMIM m iMIBIBIMI « IBIMIMI B I I BI B IBIMlBI B i a iaiM|I M IBi n i gH I M lW tn]gl ■ 

"InitEther" 

This procedure sets up vital state information for the interface and must be called before any of the other 
routines are used 



27 Aug 84 



Servcrs-59 



Call: 



procedure InitEther( 

RPort :port; 
Heap : integer) 



Parameters: 



"Rport"-port to which replies from the Ether Server should be 
sent If it is equal to NullPort, a new port is allocated. 



Exceptions: 



"Heap' -heap to be used for dynamic storage allocation. If 
equal to 0, the default data heap is used. 



""-Exceptions raised by the 'wait' routines, should be obvious, if not 
check the code. 



WH4 



"SendEtherAddress" 

Send a message to find out the local EtherNet address 
Call: 

function SendEtherAddress( 
Reply :Port; 
Max Wait: long; 
Option : SendOption ) 
: GeneralRetu'rn 



toia a innni 



"ParseEtherAddress" 

Parse the reply message containing the EtherNet address 
Call: 

function ParscEthcrAddress( 

MsgP :pMsgRGet£therAddress ) 

:integer 

Returns: 

EtherNet address 

■ IM I BI BI HlB I MlMIP IB lBI H I M i ni B I BI BI B I BIBlBI B IH I B B IBIglBmi 

"WaitEtherAddress" 

Synchronously get the EtherNet address 



27 Aug 84 



Scrvers-60 



Call: 

function WaitEtherAddress : integer; 

Returns: 

EtherNet address 



"SendEtherFilter" 

Send a message to set the ether filter - 
Call: 

function SendEtherFilter( 

Typ : integer; 
Listener : Port; 
Reply : Port; 
Max Wait : long; 
Option : SendOption) 
: GeneralReturn 

A ether filter specifies the type of ether packets that we are interested in listening for. After a filter with the 
value of Typ has been set, any incoming packets of that type cause a notification message to be sent to the 
Listener port 

■ I M I MIB I BIM I B m iMIBiaiMIMIM I Mini B IB i BIMIMIMIBIM I BIMIW m iBiaiMIMi n i M l g l MI MI ■ 

"ParseEtherFilter" 

Parse reply message containing value of ether filter. 
Call: 

function ParseEtherFilter( 

MsgP : pMsgRSetEtherFilter; 
varTyp : integer) 
:boolean; 



Returns: 



true - if the ether filter of the value Typ has been set 

false - if the filter was not set because the maximum number 
of filters was already set. Currently the maximum number of 
filters is 4. 



"WaitEtherFilter" 

Synchronously set a new value for the ether filter 
Call: 
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function WaitEtherFilter( 

Typ : integer; 
Listener : Port ) 
: boolean; 

Returns: 

same as for ParseEtherFilter. 



"SendEtherClear" 

Send message to remove an ether filler 
Call: 

function SendEtherClear( 

Typ : integer; 
Listener : Port; 
Reply : Port; 
Max Wait : long; 
Option : SendOption ) 
iGeneralRetura; 

Removes the filter of value Typ with the associated notification port of Listener. 

»M»HW B I Min i » *<HHm a i Min iWI M I BiSIBI »i a iW IMini BIM IM^ HI 

"ParseEtherClear" 

Parse message received as a result of an EtherClear message 
Call: 

function ParseEtherClear( 

MsgP : pMsgRClrEtherFilter; 
var Typ : integer ) 
: boolean; 

Returns: 

"same as for ParseEtherClear. " 



"SendEtherPacket" 

Send an ethernet packet pointed to by 'Packet', of size 'PackelWords' 
Call: 

function SendEtherPacket( 

Packet : pointer; 
PacketWords: integer; 
MaxWait : long; 
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Option : SendOption ) 
: GeneralReturn; 

Parameters: 

"Packet "-pointer to packet to be sent 
"PacketWords "-number of words in packet. 



"ParseEtherPacket" 

Copies an elhernet packet from the response message into the area pointed at by 'Packet', returning the 
number of words copied. 

Call: 

function ParseEtherPacket( 

MsgP : pMsgRecvEtherPacket; 
Packet : pointer) 
: integer; 

Parameters: 

"Packet "-Pointer to packet to be parsed. 

Returns: 

number of words in packet 



"SendPupFilter" 

Add a new socket on which to receive pup packets. 
Call: 

function SendPupFilter( 

Socket : Long; 
Listener : Port; 
Reply : Port; 
Max Wait : long; 
Option : SendOption ) 
: GeneralReturn; 



"ParsePupFilter" 

Parse return message from SendPupFilter call 
Call: 
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function ParscPupFilter( 

MsgP : pmsgrsetpupfi Iter; 
var Socket : Long ) 
: boolean; 

Returns: 

true - if the socket has been added to the list of available sockets. 

false - if the socket was already in use, or if the maximum number of 
sockets was already allocated. Currently, the maximum number of sockets 
is 4, 



"WaitPupFilter" 

Synchronously add a new socket on which to receive pup packets. 
Call: 

function WaitPupFilter( 

VAR Socket : Long; 
Listener : Port ) 
: boolean; 

Returns: 

same as for ParsePupFilter. 



"SendPupClear" 

Send message to deallocate a socket. 
Call: 

function SendPupClear( 

Socket : Long; 
Listener : Port; 
Reply : Port; 
MaxWait : long; 
Option : SendOption ) 
: GeneralReturn; 



"ParsePupClear" 

Parse message reply from SendPupClear message. 
Call: 
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function ParscPupClear( 

MsgP : pMsgRClrPupFilter; 
var Socket : Long ) 
: boolean; 

Returns: 

true - if the socket was found and deallocated, 
false - if the socket was not found 



"WaitPupClear" 

Synchronous call to allocate a pup socket. 
Call: 

function WaitPupClear( 

var Socket : Long; 
Listener : Port ) 
: boolean; 

Returns: 

same as for ParsePupClear 



"SendPupPacket" 

" Send a Pup Packet pointed to by 'PupPacket*. " 
Call: 

"function SendPupPacket( 
PupPacket : pointer; 

MaxWait : long; 
Option : SendOption 

: GeneralRcturn;" ) 



"ParsePupPacket" 

Copies the Pup packet from the PacketMessage into the 'PupPacket*. 
Call: 

procedure ParsePupPacket( 

MsgP : pMsgRecvPupPacket; 
PupPacket : pointer); 
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"FinEther" 

Deallocate resources allocated for local use. 
Call: 

procedure FinEther; 
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6 Process Manager 

6.1 Introduction 

The Process Manager controls and monitors the activity of a process. It supplements the process control 
functions of the Accent kernel. Process control signals can be sent between processes to control individual 
or groups of processes. The user can also suspend, resume, cancel and debug processes through shell or 
Window Manager commands. 

To use the Process Manager a process must be rgistered. If the process was created with Spawn it it 
automatically registered otherwise a process can be registered with the function PMRegistcrProcess. A 
process that is not registered with the Process Manager will be harder to start up and impossible to control. 

6.2 Process Trees 

Processes are organized into trees. Each process in the tree has a parent and a set of children. Registering a 
process supplies the Process Manager with: 

• the parent of the process. 

• the kernel and data ports of the new process, 

• a descriptive name for the process, 

• the window, typescript and environment manager connections, 

The parent process controls the children through Accent or the Process Manager. The parent is notified 
when a child dies through an emergency message that contains 

1. the reason for termination - "process death" if the child gives no reason 

2. run time - if available 

3. load time - if available 

4. elapsed time - if available 

A process may reregister itself with a new parent. When a parent dies surviving children are "orphans". 

63 Process Control Groups 

Processes can be controled together through Process Control Groups. Each window can only belong to one 
process group. A group can be associated with one or more windows and a process cotnrol key typed to any 
window affects all of the process group. The name of the group is located in the window icon (aliases for the 
name are in icons of other windows in the group). If a process changes it's group, it's children become 
members of the new group. If the process control window is removed, the process is "out of control" and 
can only be controlled by shell process control commands. 



Servers-67 



6.4 Process Control Signals 

The Process Manager provides 64 Process Control Signals, 7 with defined roles: 



Signal 


Default Action 


suspend 


suspend the process 


resume 


resume the process 


status 


display status in process manager window 


LevellAbort 


terminate process 


Level2Abort 


terminate process 


LeveBAbort 


terminate process 


debug 


suspend process & invoke debugger 


other 


ignore signal 



On receiving a signal a process may 

1. Send - send an emergency message saying what signal has occured (resume any suspended 
processes). 

2. Ignore - ignore signal. LeveBAbort signals cannot be ingored and will terminate the process. 

3. Default - perform the default action for the signal. 

The action for each signal may be specified independently. There are Process Manager functions 
(Emergency Messages) to send a signal to an entire process group or single process in a group. 

6.5 Keyboard and Window Manager control 

The following commands can be typed to the shell to control processes, 

Suspend <string> 
Resume <string> 
Debug <string> 
Kill <string> 
SetPriority <string> 

If the string given is a group name the command will affect the group. The command will affect a process if 
the string given is a process number or a prefix of the process name. If the string matches more than one 
process name the command fails and returns NameAmbiguous. 

These same commands can be selected from the Window Manager menu or with the Window Manager 
keyboard commands. See the User's Guide to the Window Manager for more information. 

6.6 Debugging 

The process manager can register a debug port for a process. If the process gets an uncaught exception or an 
addressing error, or if a signal is raised and not caught, the process is suspended and an emergency message 
is sent to the debug port (This is line AccInt.SetBugPort in the kernel, but intercepts signals as well as 
program errors.) The port may be set up to catch all uncaught signals or only the Debug signal. A debugger 
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can use this to keep control of a process and to intercept subsequent Debug keys (instead of starting up 
another debugger). 

The global Environment variable "DebuggerName" is the name of the debugger to run. When the 
debugger is invoked, the Process Manger first tries to run the program named in "DebuggerName". If that 
is not found, it tries to run 'Debugger.run'. If that, in turnis missing, it runs the built-in Mace debugger. If 
"DebuggerName" has the value '?' the Process Manager asks the user for the name of a run file to run as 
the debugger. 

The debugger starts up with the following environment: 

InPortst[0] Kernel Port of target process 

InPortstfl] Process Manager Port 

EMPort process Environment Manager connection for target 

UserWindow, Window and typescript for the debugger. 

UscrTypescript Process control functions on this window affect 

the Debugger, not the target process (the 

debugger may, of course, intercept them). 



6.7 Definitions 

The following definitions are found in ProcMgrDefs.pas , 
Const 

ProcMgrBase = 3600; { Process Manager messages and errors } 
SignalBase = 3800; { Signals and asynchronous returns } 

{ Error returns from ProcMgr } 

UnknownProcess = ProcMgrBase +1; 
UnknownSignal = ProcMgrBase +2; 
UnknownAction = ProcMgrBase +3; 
UnknownWindow = ProcMgrBase +4; 
WindowInUse = ProcMgrBase +5; 
NoChildren = ProcMgrBase +6; 

UnknownPort = ProcMgrBase + 7 ; { NullPort given to ProcMgr } 
Name Ambiguous = ProcMgrBase +8; 
ProcessDisowned = ProcMgrBase +9; 

{ Signals } 

MinSignal = SignalBase; 
MaxSignal = SignalBase +63; 

{ signal numbers 1..32 are reserved for Spoonix! } 

SigSuspend = MinSignal +33; 
SigResume = MinSignal+34; 
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SigStatus = MinSignal+35; 
SigDcbug = MinSignal+36; 
SigLevell Abort = MinSignal+37; 
SigLevel2Abort = MinSignal+38; 
SigLeveB Abort = MinSignal+39; 

type 

SignalName = integer; 



{ Actions } 

type 

SignalAction = (SigDefault, 
Siglgnore, 
SigSend); 



{ Statistics returned to caller } 

StatRecord = record 

RunTime: long; {microseconds} 
LoadTime: long; { microseconds } 
ElapsedTime: long; {ticks} 
KernelPort: long; { number, not port } 
Priority: integer; 
QueuelD: integer; 
ProcName: string; { Process name } 
IconName: ProgStr;{ name in Icon - group name } 
State: ProcState; 
end; 

StatArray = array[0..0] of StatRecord; 
StatList = tStatArray; 

6.8 Functions 

The following functions are found in ProcMgrUser.pas. 



PMRegisterProcess 

Register a process with the Process Manager 
Call: 

function PMRegisterProcess( 

ServPort : Port; 
HisKPort : Port; 
HisDPort : Port; 
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ProgName : string; 
HisWindow : Window; 
HisTypescript: Typescript; 
EMConn : port; 
Parent : port) 
: GeneralReturn 

Parameters: 

ServPort-PoTt to Process Manager (exported by Pascallnit as PMPort). 

HisKPort-The kernel port of the process to be registered. 

HisDPort-The data port of the process to be registered. 

ProgName-Thz name of the process, usually the .RUN file name. 
Spawn registers the parameter that it calls ProcName as the ProgName. 

HisWindow-The window associated with the process. NullPort if none. 

HisTypescript-The typescript associated with the process. 

EMConn-The port associated with a new connection to the 
Environment manager for this process. NullPort if none. 

Parent-The kernel port of the Parent Process. 

The supplied data is entered into the Process Manager Data Base and the icon name for the process's window 
is set to be ProgName. 

PMSetSignal 

Set the signal actions for a process 
Call: 

function PMSetSignal( 

ServPort : port; 
ProcPort : port; 
Signal : SignalName; 
Action : SignalAction) 
: GeneralReturn 

Parameters: 

ServPort-Poit to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-The Kernel port of the process to affect 
Signal-Signal to change action for. 
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Results: 



Action-New Action to set for signal. Actions are: 

SigSend - send a SignalMessage to the process's SignalPort 
with the signal as the reason. 

Siglgnore - completely ignore the signal. 

SigDefault - take the default action for the signal. 

Success 

UnknownProcess 
UnknownSignal 
Unknown Action 



PMSetSignalPort 

Sets the signal port (port to receive signal message for SigSend) for a process. 
Call: 



Parameters: 



function PMSetSignalPort( 

ServPort : port; 
ProcPort : port; 
SignalPort : port ) 
: GeneralReturn 



ServPortrPort to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-The Kernel port of the process to affect 
SignalPort-The port to receive SignalMsg 



PMSetDebugPort 

Sets up a port to intercept errors and default signals for a process. If the debug port exists, the default action 
for the debug signal (or all signals) will be to suspend the process and send a message to the debug port. In 
addition, the debug port will receive all Debug error messages for the process (from the kernel). 

Call: 
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function PMSctDcbugPort( 

ScrvPort : Port; 
ProcPort : Port; 
DebugPort : Port; 
DcbugSignalOnly : Boolean) 
: GeneralRetura 



Parameters: 



Results: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcPort-The Kernel port of the process to affect. 

DebugPort-Port to receive emergency message when something happens 
to the process. 

DebugS ignalOnly-lf 'TRUE, only intercept uncaught DEBUG signals. 
If FALSE, intercept ALL uncaught signals. 

Success 

UnknownProcess 

The 'SetDebugPort' call in Accent only intercepts exceptions and memory faults. This call intercepts Signals* 
as well. 

PMSaveLoadTime 

Saves the load time for a process so that it can be printed later. 
Call: 

function PMSaveLoadTime( 

ServPort : Port; 
ProcPort :Port; 
LoadTime : long) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-Pon to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-Kemel port of process. 
LoadTime-Time to load process (microseconds) 

Success 

UnknownProcess 
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PMGetWaitID 

Get the Wait ID' of a child process. The Wait ID is a 32-bit number that is returned when the child process 
dies. Its only use is to identify the dead process (the dead process' KernelPort is no longer valid, since it was 
deallocated when the process died). 
Call: 

function PMGetWaitID( 

ServPort : Port; 
ProcPort : Port; 
var WaitID : long) 
: GencralReturn 



Parameters: 



Results: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-Kcmoi port of process. 
Wzz7ZD-returns the Wait ID for the child process. 

Success 



UnknownProcess 

The 'processdeath' message is returned to the parent's DataPort, whether or not it has asked for the child's 
WaitID. 



PMGetTimes 

Returns the run and elapsed time for a process. 
Call: 

function PMGetTimes( 

ServPort : Port; 
ProcPort : Port; 
varLoadTime : long; 
var RunTime : long; 
var ElapsedTime : long) 
: GeneralReturn 

Parameters: 

ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-Kernel port of process. 



27 Aug 84 



Servcrs-74 



Results: 



LoadTime-Retums the load time for the process (microseconds). 
RunTime-Returns the run time for the process (microseconds). 
ElapsedTime-Returns the elapsed time for the process (1/60 second). 

Success 

UnknownProcess 



PMGetProcPorts 



Get the registered ports of a process. 
Call: 



Parameters: 



Results: 



function PMGetProcPorts( 

ServPort : Port; {get ports for process being 
ProcPort : Port; debugged} 
var hisWindow : window; 
var histypescript : typescript; 
var hisEMConn : Port) 
: GeneralReturn 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-Kernel port of process. 
hisWindow-retums window 
hisTypescript-Tetums typescript for process. 
hisEMConn-vetarns Environment connection for process. 

Success 

UnknownProcess 



PMTerminate 



Terminate a process. 
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Call: 



Parameters: 



Results: 



function PMTerminate( 

ServPort : Port; 
ProcPort : Port; 
Reason : long) 
: GeneralReturn 



ServPorl-Port to Process (exported by Pascallnit as PMPort). 
P roc Port-Kernel port of process. 
Reason-Reason for termination. 

Success 

UnknownProcess 



H E 1 I BM 



PMDebugProcess 



Invoke a debugger on a process. 
Call: 



Parameters: 



Results: 



function PMDebugProcess( 

ServPort : Port; 
ProcPort :Port; 
Reason : long) 
: GeneralReturn 



ServPort-Pon to Process Manager (exported by Pascallnit as PMPort). 
ProcPort-Kemel port of process. 
Reason-Reason for debugging process. 

Success 

UnknownProcess 
Failure-couldn't invoke debugger 
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PMAddCtlWindow 

Add a new window to the set of controlling windows for a process group. 
Gall: 

function PMAddCtlWindow( 
ServPort : Port; 
CtlWindow : Window; 
NewCtlWindow : Window) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-Voxt to Process Manager (exported by Pascallnit as PMPort). 
CtlWindow-an existing window for a control group. 
NewCtlWindow-a new window to add as a control window. 

Success 

UnknownWindow-CtlWmdow is not a control window for a process group. 
UnknownPort-NewCliWmdovf is NullPort. 



KHBM 



PMRemoveCtlWindow 

Removes a window to the set of controlling windows for a process group. 
Call: 

function PMRemoveCtlWindow( 
ServPort : Port; 
CtlWindow : Window) 
: GeneralReturn 



Parameters: 



Results: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 
CtlWindow-an existing window for a control group. 

Success 

UnknownWindow-CtlWmdovf is not a control window for a process group. 
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PMChangeGroup 

Changes a process (and its descendants) to a new process group. If there is already a process in the process 
group, it must be the parent of the affected process. 

Call: 

function PMChangeGroup( 
ServPort : Port; 
ProcPort : Port; 
NewWindow : Window) 
: GeneralReturn 



Parameters: 



Results: 



Serv Port-Port to Process Manager (exported by Pascal Init as PMPort). 
ProcPort-Kevnei port of process. 
Window-Window to use for new group. 

Success 

UnknownProcess 

UnknownPort-if window is NullPorL 

Windowln Use-window already controls a process group. 



vm 



PMGroupSignal 

Removes a window to the set of controlling windows for a process group. 
Call: 

function PMGroupSignal( 

ServPort : Port; 
CtlWindow : Window; 
Signal : SignalName) 



Parameters: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 
CtlWindow-One of the windows controlling a process group. 



Signal-Signs! to send. 
This is an Emergency message to the process manager. 
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PMProcessSignal 

Sends a signal to a single process. 
Call: 

function PMProcessSignal( 
ServPort : Port; 
ProcPort : Port; 
Signal : SignalName) 

Parameters: 

ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcPort-Kemel port for a process to signal. 

S/graZ-Signal to send. 
This is an Emergency message to the process manager. 

PMSuspend 

Suspend a named ( or numbered) process. 
Call: 

function PMSuspend( 

ServPort : Port; 

ProcID : string) 
: GeneralReturn 

Parameters: 

ServPort-Poii to Process Manager (exported by Pascallnit as PMPort). 

ProcID-Name of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 

Results: 

Success 

UnknownProcess 
NameAmbiguous 

If the name designates a process group, it sends the Suspend signal to the process group. If the name designates 
a single process, it suspends the process. If the process has a DebugPort set, it also send an M_DebugMsg 
message to the debug port, with SigSuspend as the reason (unless the debug port is set to DebugSignalOnly). 
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PMResume 

Resume a named (or numbered) process. 
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Call: 



Parameters: 



function PMSuspend( 

ServPort : Port; 
ProcID : string) 
: GeneralReturn 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcID-Name of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 



Results: 



Success 

UnknownProcess 
Name Ambiguous 

If the name designates a process group, it sends the Suspend signal to the process group. If the name designates 
a single process, it suspends the process. If the process has a DebugPort set, it also send an M_DebugMsg 

tviflpp/7/>/? tr\ iVt n Aniens* r%,r\ifi u>/*/i CmCi/CTSAM// /re ltt/> vspsresyyt /nw/tfrp flirt sfahittrt T>/-\ri to raf is\ T^alyii et^? i ovist! f^vilyti 

PMDebug 

Invokes the debugger on a named (or numbered) process. 
Call: 

function PMDebug( 

ServPort : Port; 
ProcID : string) 
: GeneralReturn 



Parameters: 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcID-'Name of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 



Results: 



Success 

UnknownProcess 
NameAmbiguous 

If the name designates a process group, it sends the Suspend signal to the process group. If the name designates 
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a single process, it suspends the process. If the process has a DebugPorl set, it also send an MDebugMsg 
message to the debug port, with SigDebug as the reason. 



PMKill 



kill a named (or numbered) process. 
Call: 



Parameters: 



function PMKill( 

ServPort :Port; 
ProcID : string) 
: GeneralReturn 



ServPort-Port to Process Manager (exported by Pascallnit as PMPort). 

ProcID-Na.m& of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 



Results: 



Success 

UnknownProcess 
NameAmbiguous 

If the name designates a process group, it sends the Suspend signal to the process group. If the name designates 
a single process, and the process does not have a DebugPort set, it terminates the process with reason= 
SigLevell Abort. If the process has a DebugPort set, it instead sends a MJDebugMsg message to the debug 
port, with SigLevell Abort as the reason (unless the debug port is set to DebugSignalOnly). 



PMSetPriority 

Sets the priority of a named (or numbered) process, or of all of the processes in a process group. 
Call: 

function PMSetPriority( 
ServPort :Port; 
ProcID : string; 
priority : integer) 
: GeneralReturn 

Parameters: 

ServPort-Pon to Process Manager (exported by Pascallnit as PMPort). 

Proc/P-Name of group, prefix of processname or kernel port number of 
process as returned by PMGetStatus. 
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Priority-Desired run priority for process: 
0: lowest priority 
15: highest priority 

Results: 

Success 

UnknownProcess 
NameAmbiguous 
BadPriority 

Changes the priority of the process or of all processes in the process group. 



PMBroadcast 

Print a message in the Process Manager Window. This is used to display 'system' messages. 
Call: 

function PMBroadcast( 

kJVl U Ull ■lUllt 

s : string) 
: GeneralReturn 

Parameters: 

ServPort-Voft to Process Manager (exported by Pascallnit as PMPort). 
^-String to display. 

Results: 

success 



PMGetStatus 

Returns status for one or more processes. 
Call: 

function PMGetStatus( 
ServPort : Port; 
ProcID : string; 
var Stats : StatList; 
var Stats.Cnt : long) 
: GeneralReturn 

Parameters: 
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Results: 



ServPori-Port to Process Manager (exported by Pascallnit as PMPort), 

ProcID-Can be: 

Process group name - 

returns status for all processes in group. 
Pattern to match (as in file name patterns) - 

returns status for all matching process names 
Process number for process - 

returns status for that process. 
Null String; 

returns status for all registered processes. 

■Sta/s-Returns a pointer to the array of status records, one for 
each process whose name matches ProcID. 

Stats Oif-Returns number of records in Stats 



Success 

UnknownProcess-name didn't match any process 

Asynchronous (Emergency) Messages 

Message sent to DebugPort to report an action on another process. (This is the same as the kernel's M 
DebugMsg.) 



Parameters: 

ATPor^-Kernel port of process affected. 
.4rg/-Always 0 (present for historical reasons) 

/4rg2-Reason for DebugMessage: 

if the process was halted by an error, this is 
the GeneralReturn value describing the error 
(MemFault, UncaughtException, ...) 

if the process has a Process Manager Debug Port set 
(by PMSetDebugPort), and a signal was raised on 
process and not sent or ignored, this is the name 
of the signal that was raised. 



type DebugMessage = record 

Head : Msg; {Accent message header} 
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: TypeType; { (TypePT, 32)} 


KPort 


: Port { Kernel port of process affected } 
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tArg2 


: TypeType; { (Typelnt32, 32) } 


Arg2 


: Long; { What happened, fi eld 2: 




GeneralReturn value f or 



error or signal. } 

end; 



Asynchronous (Emergency) Messages 

Message sent on process termination 



Parameters: 

WaitID-W ait ID of process that died, as returned from PMGetWaitlD. 

Ppncnn— T?£»acn« fr\r r\rf\ne> cc AaotVx' 

if killed by terminate (in Acclnt), 
PROCESSDEATH 

if killed by PMTerminate (in ProcMgr), 
the Reason given to PMTerminate. 

if the process re-registered with a different parent, 
ProcessDisowned. - . 

if the process was killed by a SigLevel[l,2,3] Abort, 
the signal value. 

LoadTime-CPU time to load process (microseconds) 

RunTime-CPU time to run process (microseconds) 

ElapseaTime-Total time elapsed from PMRegisterProcess until 
termination (60Hz clock ticks). 



const ProcessDeathMsgID= 3800; 

type ProcessDeathMsg = record 

Head : Msg; {Accent message header} 
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tWaitID : TypeType; { (typclnt32, 32) } 
WaitID : long; { Wait ID of process, 

returned f rom PMGetWaitID } 
tReason : TypeType; { (Typelnt32, 32) } 
Reason : long; { reason for process death } 



: TypeType; { (Typelnt32, 32) } 
: long; { process Load time 
(microseconds) } 

: TypeType; { (Typelnt32, 32) } 
: long; { process Run time 
(microseconds) } 

tElapsedTime : TypeType; { (Typelnt32, 32) } 
ElapsedTime : long; { Elapsed time 
(ticks) } 

end; 



Asynchronous (Emergency) Messages 

Message sent for signal to a process: this is sent to a process's SignalPort, or to its DATAPORT if the 
SignalPort has not been set or is NullPorU 



tLoadTime 
LoadTime 



tRunTime 
RunTime- 



Parameters: 

CtlWindow-Wmdow that the signal was sent from. If the signal was 
sent only to one process, it is the window that heads the 
control group for the process. 



Signal-signal sent to process. 



const SignalMsgID = 3801; 

type SignalMsg = record 

Head : Msg; {Accent message header} 

tCtlWindow : TypeType; { (TypePt, 32) } 
CtlWindow : window; { Window that signal was 

received on } 
tSignal : TypeType; { (Typelntl6, 16) } 
Signal : SignalName; { signal received } 

end; 
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7 Sesame: Interface to Prelimary Sesame File System 

Sesame provides routines to read, write and get information about files, given an absolute pathname for the 
file. The port to this server ( the ServPort parameter) is exported as SesPort from Pascallnit. See the section 
on Sesamoid in the Sesame: The Spice File System Manual for more information. 

7.1 Type Definitions 

The following definitions are from SesameUser.pas. 



APath_Name = string[Path_Name_Size]; { An abs. pathname } 
Wild_APath_Name = string[Path_Name_Size]; { A wild abs. pathname } 
Entry.Name = string[Entry_Name.Size]; { A pathname component } 



{ Name.Flags: Flags giving desired treatment of names in Name Server calls. 
{ Note that specific flag values may be illegal for certain calls, and 
{ must be zero. 



const 

NFlag_Deleted = #000001; { Allow deleted names } 
NFlag_NoNormal = #000002; { Disallow normal (not deleted) names } 
NFlag^RESERVED = #177774; { These bits reserved for expansion } 
type 

Name.Flags = 0 .. #3; 



{ Name_Status: Flags useful for determining the disposition of a name in 
{ the name data base. 

const 

NStat.Deleted = # 000001 ; { Set if name is deleted } 
NStat.High = #000002; { Set if name is highest undeleted version } 
NStat_Low = #000004; { Set if name is lowest undeleted version } 
NStatRESERVED = #177770; { These bits reserved for expansion } 
type 

Name.Status = 0 .. #7; 



{ Entry.Type: The kinds of objects which can be in the name data base. 



const 
Path_Name_Size 
Entry_Name_Size 

type 



= 255; { Number of characters in a Path_Name } 
= 80; { Number of characters in an Entry_Name } 
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const 

Entry.All =0; { Special value referencing all entry types } 
Entry.File =1; { Entry .Data is a File.ID } 
Entry.Directory = 2; { Name refers to another level of the 

name hierarchy. Entry .Data is empty. } 
Entry.Port =3; { Entry _Data is a port } 
type 

Entry.RESERVED = 4 #377; { These values reserved for expansion } 
Entry.UserDefined = #400 .. #77777; { Values available to the user } 
type 

Entry Type =0.. #77777; 



{ Entry_Data: The variant data record dependent upon the Entry.Type value, 
type 

Entry_Data = record case Entry.Type of 
Entry.File : ( {EDFilelD : File.ID - Not Yet Implemented} ); 
Entry.Directory : ( ); 
Entry>ort : ( EDPort : Port ); 
#400 : ( EDBytes : packed array [0..255] of bit8 ); 
#401 : ( EDWords : array [0..127] of integer ); 
#402 : ( EDLongs : array [0..63] of long ); 
#403 : ( EDString: string[255]); 
end; 

{ Entry.List.Record: ScanNames returns array of Entry.List.Record. 



Entry.List.Record = record 
EntryName : Entry _Name; 
Entry Version : long; 
Entry Type ; Entry.Type; 
NameStatus : Name.Status; 
end; 

Entry.ListArray = array [0..0] of Entry.List.Record; {hack} 
Entry.List = t Entry JList.Array; 

{ Valid.Name.Chars: Those 7-bit ascii characters which can occur in an 
{ entry name without being quoted. Note that to match uppercase, 
{ uppercase letters also have to be quoted. 

const 

Valid Name Chars = { Put in a string since can't put in a set } 
'$-."+0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ.abcdefghijklmnopqrstuvwxyz'; 
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{ Separator characters for parts of Path_Name syntax, 
const 

Dir_Separator = V; { Directory separator } 
Ver_Separator = { Version number separator } 
Quote_Char = 'V; { Quote character for "runny" characters } 

Up_onc_Directory = '../'; 
This_Directory = './'; 

{ Group.ID: An identifier for a User Group 
type 

Group_ID = long; 



{ File.Data: A pointer to a file mapped into memory 



type 

File.Data = pointer; { A pointer to data for file calls } 



{ PrintName: A short string name in the file header. 



const 

Print.Name.Size = 80; { Number of characters in a file PrintName } 
type 

PrintName = string[Print.Name.Size]; { A print name string } 



{ Data.Format: A user-defined longword for storing data format information. 
{ System- defined values are given below. User-defined values must 
{ have a non-zero high word (#200000 or greater). These values are 
{ intended to be used by programs which need to know about data formats 
{ in order to convert from one format to another (such as FTP). 

const 

DForm.Unspecified = 0; { Unspecified data format } . 



DForrn 8_Bit = 8; 

DForm] 16_Bit = 16: 

DForm_32.Bit = 32; 

DForm.36.Bit = 36: 



{ 8 bit binary data } 
{ 16 bit binary data } 
{ 32 bit binary data } 
{ 36 bit binary data } 
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DForm CRLFTcxt = #413; 
DForm LFText = #410; 

DForm_Press = #1000; 
type 

Data.Format = long; 



{ CRLF delimited text } 
{ LF delimited text } 

{ Press file format data } 



{ File_Header: How the user perceives the file header information. It is 
{ actually generated by the GetFileHeader style calls from the real 
{ header. 



type 

File_Header = packed record 
FileSize : long; { Size of file in bytes } 
DataFormat : long; { Advisory data format } 
PrintName : Print_Name; { The file print name } 
Author : Group _ID; { Who wrote the file } 
CreationDate : Internal_Time;{ When it was written } 
AccessID : Group.ID; { Who last accessed the file } 
AccessDate : Internal.Time;{ When it was last accessed } 
FHdr.RESERVED : array [56..64J of integer; { Pad for expansion } 
end; 



{ Error return values 
const 

Sesame.Error.Base = 1200; 



NameNotFound = Sesame.Error.Base + 1; 
DirectoryNotFound = Sesame.Error Base + 2; 
DirectoryNotEmpty = Sesame.Error. Base + 3; 
BadName = Sesame.Error Base + 4; 
InvalidVersion = Sesame.ErrorBase + 5; 
InvalidDirectoryVersion 

= Sesame.Error Base + 6; 
BadWildName = Sesame.Error Base + 7; 
NotAFile = Sesame.Error Base + 8; 
NoAccess = Sesame.Error.Base + 9; 
NotSamePartition = Sesame.Error.Base + 10; 
ImproperEntryType = Sesame.Error.Base + 11; 
NotADirectory = Sesame.Error.Base + 12; 



7.2 Procedures and Functions 



The following procedures and functions are found in SesameUser.pas. 
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Several of the calls are provided with two or more forms, with one being a subset of the other. Where this is 
the case, the subset form will have a name prefix of Sub, whereas the full form of the call will have a name 
prefix ofSes. 

InitSesame 

Initialize the local copy of this module. 
Call: 

procedure InitSesame(RPort : port); 



SubReadFile 



Simplest way to read a file. 
Call: 



Parameters: 



Results: 



Function SubReadFile( 

ServPort : port; 
APathName : APath_Name; 
var Data : File_Data; 
var Data.Cnt : long) 
: GeneralRetura 



ServPort-port to the Name Server 
apathname-the absolute pathname to read the data from 
data pointer-* pointer to the data read in memory 
DataCnt-thQ total number of bytes read 

success-thQ data was successfully mapped into memory 

no such name-no entry was found under apathname 

access vioIatiotHhe requesting client tried to read a file 
for which he did not possess rights 

not a file-the entry found under apathname was not a file 

no such file 7Z>-the file associated with the entered 
ID could not be found 

The SubReadFile request is used to map the data associated with the given filename into memory. Note that we 
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map the entire file in, thus there are no arguments specifying the size or position of the data to be read. We can 
get away with mapping the whole file since we actually will only bring in the pages which are touched, the rest 
being backed to secondary storage. Holes in the file will be mapped in as valid zero pages which will actually be 
created if written to. 

■ ■ ■ ■■■■■■■ ■ IMIMIMIBIMI MI MI MIM IM IM IMIMIMI M | M |MI Mf |ni|MIBll HMIHHBi l B il1l1| M | U 

SesReadFile 

Read a file with complete specification 
Call: 

Function SesReadFile( 

ServPort : port; 
var APathName : APath.Name; 
var Data : File .Data; 
var Data_Cnt : long; 
var DataFormat : Data .Format; 
var CrcationDate: Internal .Time; 
var NamcStatus : Name .Status) 
: GeneralReturn 

Parameters: 

ServPort-pon to the Name Server 
apathname-\he absolute pathname to read the data from 
Data-a. pointer to the data read in memory 
Data_Cnt-the total number of bytes read 

DataFormaHme of {unspecified, text, bit8, bitl6, bit32, bit36, press, ...} 
CreationDate-\he date and time the file was written 
NameStatus-low version, high version 

Results: 

success-the data was successfully mapped into memory 

no such name-no entry was found under apathname 

access violation-the requesting client tried to read a file 
for which he did not possess rights 

not afile-the entry found under apathname was not a file 

no such file ID-the file associated with the entered 
ID could not be found 
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The SesReadFile request is a long form of the SubReadFile call. It returns several parameter values which the 
short form does not. 

SubWriteFile 

Simplest way to write a file 
Call: 

Function SubWriteFile( 

ServPort : port; 
var APathName : APath.Name; 
Data : File_Data; 
Data.Cnt : long; 
DataFormat : Data .Format; 
var CreationDate: Internal _Time) 
: GeneralReturn 

Parameters: 

ServPort-port to the Name Server 
Apathname-the absolute pathname to write the data to 
Data-a pointer to the data in memory 
DataCnt-the number of bytes to be written 

DateFormat-one of {unspecified, text, bit8, bitl6, bit32, bit36, press, ...} 
CreationDate-thQ date and time the file was written 

Results: 

success-the data was written under the name returned 

access violation-the requesting client tried to write a file for which he did not possess 
rights 

conflicting version-tiie explicit version number was less than or equal to that of an 
existing version 

allignment error-the data was not on a page boundry 
The SubWriteFile request is used to enter a new name into the directory structure and write a file under that 
name. This short form of the call picks up defaults for unspecified parameters from previous versions or 
directory defaults. The user must have CreateNames rights in the directory or Supercede rights on the previous 
version. Empty pages need no disk pages assigned to them. 
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SesGetFileHeader 



Get file header information 
Call: 



Parameters: 



Results: 



Function SesGetFilcHeader( 

ServPort : port; 
APathName : APath Name; 
var FilcHeader : File_Header) 
: GeneralReturn 



ServPort-port to the Name Server 

Apalhname-the absolute pathname with which to find the file 

FileHeader-a data structure containing the 
fields of the file header. 

success-thc header data was successfully returned 

no such name-no entry was found under apathname 

access violation-the requesting client tried to read a file header 
for which he did not possess rights 

not afile-the entry found under apathname was not a file 

no such file ID-the file associated with the entered ID 
could not be found 

The SesGetFileHeader request is used to return fields from the file header. 



SesReadBoth 

Read the contents and file header information of a file 
CalL- 
Function SesReadBoth( 

ServPort : port; 
var APathName : APath _Name; 
var Data : File .Data; 
var Data.Cnt : long; 
var FileHeader : File .Header; 
var NameStatus : Name .Status) 
: GeneralReturn 

Parameters: 
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ServPort-port to the Name Server 

Apathname-the absolute pathname with which to find the file 

Data-a pointer to the data read in memory 

DateCnt-ihe total number of bytes read 

FileHeader-a data structure containing the 
fields of the file header. 

AfamaS/atas-deleted/undcleted, low version, high version 

Results: 

success-the header data was successfully returned 

"no such name"-no entry was found under apathname 

"access violation"-thQ requesting client tried to read a file 
header for which he did not possess rights 

"not aJHe"-\hQ entry found under apathname was not a file 

"no such file ID"-the file associated with the entered ID 
could not be found 

The SesReadBoth request is used to return both the data from a file and fields from its header. 

SubLookUpName 

Lookup a file ID 
Call: 

Function SubLookUpName( 
ServPort : port; 
var APathName : APath.Name; 
var EntryType : Entry .Type; 
var EntryData : Entry .Data; 
var NameStatus : Name .Status) 
: GeneralReturn 

Parameters: 

ServPort-pon to the Name Server 

Apathname-tiie name to be looked up (may not 
contain wildcard characters) 

EntryType-ftie type value of the entry found. Some example 
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values arc File, Directory, and Port. 

EntryData-a variant field dependent upon the entry type. 

A File ID will be returned here for a File entry, whereas there 
will be no data returned for a Directory- all 
that this call will tell you about a directory 
is that it exists. 

AfameSVa/Ms-deletcd/undeleted, low version, high version 

Results: 

success-ttiQ name was successfully looked up. 

name not found-thc specified name was not found 

access violation-\he client does not have sufficient rights to 
look up the given name 

This function provides a simple way to look up a name. If any entry encountered during the parsing of 
apathname is of type Symbolic Link, a macro expansion is performed using the value of that entry in place of 
the corresponding name in apathname. If the final result is of type FID or IPC Port, the corresponding FID or 
IPC port is returned If it is of type Directory no entry data is returned, but entry type specifies the fact that a 
lookup on a directory name was done. If apathname does not contain a version number, the most recent version 
is assumed 



SubTestName 

See if a file exists 
Call: 



Function SubTestName( 

ServPort: port; 
var APathName : APath.Name; 
varEntryType : Entry .Type; 
var NameStatus : Name .Status) 
: GeneralRetum 

Parameters: 

ServPort-port to the Name Server 

Apathname-the name to be looked up (may not 
contain wildcard characters) 

EntryType-the type value of the entry found. Some example 
values are File, Directory, and Port. 

NameStatus-deteted/undeleted, low version, high version 
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Results: 

success-ihe name was successfully found 

name not found-\he specified name was not found 



access violation-\he client does not have UseNames rights 
on the name's directory 

SubTestName is like SubLookupName except that it never returns the entry data associated with a name, but 
only the entry type. Note that this only requires UseNames rights on the parent directory, whereas 
SubLookupName requires Lookup rights on the name itself- a much stronger requirement. It is anticipated 
that this call will be used when all that is desired is to test for the existance of a name, and to determine its 
type. 

WMH»HHtWBWHMOHH>HWH»HHWH IIt8III IBHW» W 

SubEnterName 

Enter a file or port name in a directory 
Call: 

Function SubEnterName( 

ServPort : port; 
var APathName : APath.Name; 
EntryType : Entry .Type; 
Entry Data : Entry .Data) 
: GeneralReturn 

Parameters: 

ServPort-port to the Name Server 

Apathname-the name to be entered into the directory structure 

EntryType-the type value of the object to be entered. Some 
example values are File, Directory, and Port. 

EntryData-a variant field dependent upon the entry type. 

For instance, this field must contain a File ID for type File, and 
an IPC port for type Port. For type Directory, this field 
is left empty, seeing as how the user can't write any directory data 
directly. Use of this call with entry type Directory enters a 
new directory, thus no special call is needed for that purpose. 

Results: 

success-apathnamewas successfully entered 
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conflicting version-thc version number specified in 

apathname was less than or equal to that of an already existing 
version 

access violation-thc client does not possess CreateNames 
rights in the specified directory 

invalid directory version-only one version number of a 
directory is allowed 

The SubEnterName request is used to place a name and entry value pair in the directory structure. It requires 
CreateNames permission in the directory within which the name is being entered if no version of the name 
already exists else if a version of the name already exists, then Supersede privileges on the name are needed If 
a previous version of the name already exists in the directory and no version number is specified in apathname, 
the name is entered with the next higher version number. If a previous version of the name already exists and a 
version number is specified in the name, then it must be greater than the highest version number so far. If no 
previous version of the name has ever existed, then version one is assigned if none is specified in apathname, 
otherwise the specified version is used 



SubDeleteName 



remove a name from a directory 
Call: 



Parameters: 



Results: 



Function SubDeleteName( 

ServPort : port; 
APathName : APath_Name) 
: GeneralReturn 



ServPort-thQ name to be deleted 
Apathname 

success-the name was successfully deleted 

nonexistent name-the name specified does not exist 

access violation-the user does not possess DeleteNames 
rights on the name specified 

name already deleted-the given name was already deleted 

directory not emp/y-illegal to delete a non-empty directory 
The SubDeleteName request is used to delete a name from a directory. It requires DeleteNames permission in 
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the directory or Delete permission on the name. The name is marked as deleted but remains in the directory 
and is queued for expunging by the Migration Server. If no version number is specified then the lowest version 
in the directory will be deleted 
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rename a file or port 
Call: 



Parameters: 



Results: 



SubReName 



Function SubReName( 

ServPort : port; 

OldAPathName : APath_Name; 
var NewAPathName : APath .Name) 
: GeneralReturn 



ServPort-port to the Name Server 

OldAPathName-absdlutQ pathname of the object to be renamed 
NewAPathName-ntw name to enter the object under 

success-the name was successfully changed 



access violation-the client either does not have the proper rights 
to delete old apathname or to enter new apathname 

SubRename enters the object specified by old apathname into into the global name space as new apathname 
and then removes the old apathname. The access control list of the object is moved with it. 

SesScanNames 

Returns a list of names in a directory 
Call: 

Function SesScanNames( 

ServPort :port; 

WildAPathName : Wild APath Name; 

NameFlags : Name .Flags; 

EntryType : Entry .Type; 
var DirectoryName : APath .Name; 
var Entry List : Entry .List; 
var EntryList.Cnt : long) 
: GeneralReturn 

Parameters: 
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ServPort-\hz absolute pathname to be scanned 

(may contain wildcard characters in the terminal component) 

WildAPathName 

NawieF/ags-inhibit/allow deleted/undeleted names 

EnlryType-\he entry type being scanned for. The special type 
designator All may be given, in which case names of all entry 
types are returned. 

DirectoryName-the absolute pathname of the directory in which 
matches occured 

EntryList-the sorted entry names, types, version numbers 
and name status flags 

of all names matching wild apaihname in the first element of 
search list where a match occured 

EntryList_Cnt-\hQ actual number of list elements 
returned. Will be zero if no match occured. 

Results: 

success-the given wild absolute pathname was successfully scanned 

access violatiorHhQ client does not possess 
ReadNames rights on the directory to be scanned 

illegal pathname-wildcards were found in 

wild apaihname at other than the terminal component 

The SesScanNames call is used to search for a given pattern in a specified directory. It will sort and return all 
the matches to the given pattern in the directory. Optionally, names only of a specific entry type can be scanned 
for. Symbolic links are not expanded, and are returned by this call. Depending on the value of name flags, only 
active names, deleted names or both are considered If no version number is specified, then the highest existing 
version of the name is returned If the version number is wildcarded, then all existing versions of the name are 
returned The version field for directory and symbolic link entries will be returned as zero. Note that 
wildcarding is permitted only in the terminal component of wild apathname. This call requires either 
ReadNames access on the directory being scanned, in which case all matches will be returned, or else Visible 
access on each match which is to be returned 
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8 TimeServer 

8.1 Introduction 

The Time Server provides all of the time facilities for Accent. It can return the time in a number of different 
formats. 

Internally, time is kept as the number of milliseconds since midnight, November 17,1858 Greenwich Mean 
Time (the Smithsonian time standard). In order to store the time efficiently, it is kept as an ordered pair, the 
first component representing the number of weeks that have passed since the base date-time and the second 
component representing the number of milliseconds that have passed in that week. This format also allows 
efficient comparison of times. Conversions to local time are done using a time zone index and information 
regarding whether or not to apply daylight savings time. 

The zone record, Zonejnfo, allows you to specify and receive zone information. Both the zone number and 
application of daylight savings time may be either specified explicitly or defaulted, depending on the 
settings of the UseTimeZone and UseDaylight bits. The zone record is used in User Time. 

The date and time information in User_Time is broken down into fields for input and output. Both the time 
zone index and application of daylight savings time can be either explicitly specified or defaulted through 
use of the Zone.Info fields. The Weekday field is unused for input 

8.2 Definitions 

The following definitions are from TimeDefs.pas. 

Internal.Time: a record containing the date and time in Greenwich 
Mean Time. This is the Smithsonian Institute's time standard. 
To optimize space usage, we store 
time as an ordered pair, the first representing the number of 
weeks which have passed since 17-Nov-1858, when the 
Smithsonian time standard began. The second represents the 
number of milliseconds which have passed in that week. 

type 

Internal_Time = record 
Weeks : integer; { Number of weeks since 17-Nov-1858 } 
MSecInWeek : long; { Number of milliseconds in that week } 
end; 

Date.Fields: fields necessary for representing date information 
without respect to the time. Used in by User_Time. 

type 

Date_Fields = packed record 
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Year : integer; { Such as 1982 } 

Month : 1 .. 12; { 1 = January, 12 = December } 

Day : 1 .. 31; 

Weekday : 0 .. 6; { 0 = Monday, 6 = Sunday (output only) } 
end; 



Time_Ficlds: fields necessary for representing time information 
without respect to the date. Used in UscrTime. 

type 

Time.Fields = packed record 
Hour : 0 .. 24; 
Minute : 0 .. 59; 
Second : 0 .. 59; 
Millisecond : 0 .. 999; 
end; 



Zone.Info: this record allows the user to specify and receive time 
zone information. Both the zone number and application of 
daylight savings time may be either specified explicitly, or 
defaulted, depending upon the settings of the UseTimeZone and 
UseDaylight bits. Used in UserTime. 

type 

Zone_Info = packed record 
TimeZone : integer; { Increasing minutes west from GMT. 

GMT = 0, EST = 5*60, CST = 6*60, ... 

Used only if UseTimeZone is set } 
UseTimeZone : boolean; { True when TimeZone field is valid, 

else false when local time zone is 

to be used. } 

Daylight : boolean; { True if daylight savings time is to 

be applied. Used only if 

UseDaylight is set } 
UseDaylight : boolean; { True if Daylight savings field is 

valid, else false when the system 

def ault for daylight savings time 

application is to be used. } 

end; 



UscrTime: Date and Time informatien broken down into fields as the 
user would want to use it for input and output Both the time 
zone index and application of daylight savings time can be 
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either explicitly specified, or defaulted through use of the 
Zonelnfo fields. The Weekday field is unused for input 



type 

User.Time = packed record 

Date : Date_Ficlds; 

Time : Time.Fields; 

Zone : Zone_Info; 
end; 



The following flag values may be ORed together to form TimeFormat values. 



const 

TF_Weekday = # 000001; { If set output the day of the week 

according to the setting of 

TF FullWeekday else don't output 

the day of the week } 
TF FullWeekday = #000002; { If set output full text for the 

weekday else the 3- letter 

ahhroiMati/yn f\A r\nr^o\j /\A/\r\\ \ 

TF.NoDate = # 000004; { If set do not output date and ignore 

fl ags through TF.NoTime } 
TF.FullMonth = #000010; { If set output full text for the 

month when the month is alphabetic 

else the 3- letter abbreviation . 

(March/Mar) } 

TFJullYear = # 000020; { If set output the year as a 4-digit 
number else the year is is output as 
a 2- digit number if in the range 
1900-1999 (1982/82)} 

{ The next six settings are mutually exclusive } 

TF Dashes = #000000; { Output date as day-month-year 
(22-Mar-60)} 

TF Spaces = #000040; { Output date as day month year 
(22 Mar 60)} 

TF Reversed = #000100; { Output date as month day, year 
(Mar 22, 60)} 

TF Slashes = #000140; { Output date as month/day/year 
(03/22/60)} 
{ #000200 is reserved for future expansion} 
{ #000240 is reserved for future expansion} 
TF ANSI = # 000300; { Output date according co AN5TX3.30-1971. 
Also slightly afT ects time formatting. 
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(600322)} 

TF.ANSI.Ordinal = #000340; { Similar to TF ANSI but 3-digit day-of-year 
instead of month and day. 
(60082)} 

TF_DateFormat =#000340; { A mask allowing us to examine the above. } 

TF_NoTime = #000400; { If set do not output time and ignore 
fl ags through TF.NoColumns } 



{ The next two settings are mutually exclusive } 

TF_NoSeconds = #001000; { If set do not output the seconds } 
TF.Milliseconds = #002000; { If set output milliseconds as 

hh:mm:ss.sss else omit them 

(17:00:00.001/17:00:00) } 



TF.12.Hour = # 004000; { If set output the time in 12-hour 
format with 'am' or 'pm' following the 
time else output in 24- hour format 
Note that exact NOON outputs neither 'am' 
nor 'pm' because 12:00am is 0000 and 12:00pm 
is 2400. Use of TF_12_Hour with TF ANSI or 
TF.ANSI.Ordinal is supported but not 
recommended f or a number of reasons. If used 
with either ANSI format, however, the codes 
'A', 'P\ and 'N' are used for am, pm, and 
noon, respectively. 
(5:00:00pm/17:00:00)} 

TF.TimeZone = #010000; { If set output the time zone as -zzz 
after the time else omit it 
(17:00:00- EDT/17:00:00) } 



TF_NoColumns = #040000; { If set output numeric date/time 

quantities in the smallest fi elds 

into which they will fi t, else 

output them in fi xed size fields. If 

not set, the date/time will be 

output in fi xed length fields, thus 

making this format appropriate for 

columnar display. Note that TF.FullMonth 

and TF .Full Weekday are currently NOT padded 

with blanks, even if TF.NoColumns is off. } 
TF.BlankPad = #020000; { If set, pad fixed- width numbers with blanks 

instead of zeroes WHERE REASONABLE. Ignored 

if TF.NoColumns is set. } 



TF Never = # 100000; { If set allow the distinguished time 
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value NEVER to be output as the 
string 'Never' else signal an 
error} 

The following flags arc returned to indicate which fields of the 
date and time were present upon parsing a date/time string. 



const 

TP Weekday = #000001; { Weekday present } 

TP Date = #000002; { Date present} 

TP Time = #000004; { Time present } 

TP^Zone = #000010; { TimeZone present } 

TP Never = #000020; { Time input was NEVER } 

TP RESERVED = # 177740; { Reserved for expansion } 



String.255: The maximum length string. We parse dates from such strings. 
This definition should probably be somewhere else. 



type 

String.255 = string[255]; 



83 Exceptions 

BadDateTime This exception is raised if a bad date/time value is 

passed to any of the TimeServer routines, or if the TimeFormat 
flags (for conversion to String format) are invalid. 



TimeNotlnitialized This exception is raised if the system date, time, 
and time zone have not been set 



8.4 Procedures 

The following procedures are from TimeUser.pas. 

aiat a Haiai B iBi B iB i aiBiEiBiBiaiBiBaaiBi B iaiaiBaaiBiB 

SetDateTime 

Sets current date and time. 
Call: 

Procedure SetDateTime( ServPort : port; 
ITime : Internal Time) 

Parameters: 

ServPort-TunePort (service port to Time Server) 
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/7/we-Internal_Time record for time to set 

Returns: 

Raises TimeNotlnitialized if system time zone and daylight switch have 
not been set 



SetSystemZone 

Sets the system defaults for time zone and whether to use Daylight time. 
Call: 

Procedure SctSystemZonc( ServPort : port; 
TimeZone : integer; 
DSTWhenTimely : boolean) 



Parameters: 



ServPorl-TimcPort (service port to Time Server) 

TimeZone-System time zone to set (refer to the constant definitions). 

DSTWhenTimely-WhetheT to use daylight time during the USA daylight 
time interval. 



GetDateTime 

Gets current time, in Internal Time formal 
Call: 



Parameters: 
Returns: 



function GetDateTime (ServPort : Port) 
: Internal Time 



Sen^ort-TimePort (service port to TimeServer) 
Raises TimeNotlnitialized if system time has not been set 



GetUserTime 

Gets current time, in User Time format, according to system time zone and daylight time defaults. 



Call: 
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function GetUserTime ( ServPort : Port) 
: User Time 



ServPort-TimcPort (service port to Time Server) 



Raises TimeNotlnitialized if system time has not been set 



function GetStringTime( ServPort : Port; 

TimeFormat : integer) 
: String 

Gets current time, in string format. 
Call: 

GetStringTime 

Parameters: 

ServPort-TimePort (service port to Time Server) 



Returns: 



TimeFormat-Format for the string (refer to the constant definitions) 
Raises TimeNotlnitialized if system time has not been set 



HBM 



TIntToZone 

Converts internal time to user time, according to supplied time zone. 
Call: 

function T.IntToZone ( ServPort : port; 

ITime : Internal _Time; 
WantZone : Zonejnfo) 
: User Time 



Parameters: 



Returns: 



ServPort-TimoPon (service port to Time Server) 
/r/ffie-Internal.Time record 

WantZone-ZoneJnfo record containing Zone and daylight desired. 
User Time record representing ITime. 
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TIntToUser 

Converts internal time to user time, according to supplied time zone and daylight time defaults. 
Call: 

function TIntToUser ( ServPort : port; 

ITime : Internal .Time) 
: User_Time 

Parameters: 

ServPort-TimePon (service port to Time Server) 
/r/me-Internal.Time record 

Returns: 

User Time record representing ITime. 



TUserToInt 

Converts user time value to internal time. 
Call: 

function TUserToInt ( ServPort : port; 
UTime : User .Time) 
: Internal.Time 

Parameters: 

ServPort-TimePon (service port to Time Server) 
£/r/me-User_Time record 

Returns: 

InternalTime corresponding to UTime, 



T UserToString 

Converts a user time record to a string representing the time, according to the conversion parameters. 
Call: 

function TUserToString ( ServPort : port; 
UTime : User .Time 
TimeFormat: integer) 

: String 
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Parameters: 



Returns: 



ServPort-TimoPovt (service port to Time Server) 
UTime-UserTime record 

TimeFormat-Format desired for the output (refer to the constant 
definitions) 

A string representation ofUTime. 



W i l li 
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TIntToString 

Converts an internal time record to a string representing the time, according to the conversion parameters. 
The system defaults for time zone and daylight time are used. 

Call: 



Parameters: 



Returns: 



function TIntToString ( ServPort : port: 
ITime : Internal .Time 
TimeFormat: Integer) 

: String 



ServiVf-TimePort (service port to Time Server) 
/r/me-Interaal Time record 

TimeFormat-Format desired for the output (refer to the 
constant definitions.) 



A string representation of ITime. 



T StringToUser 



Converts a string to a user-time record 
Call: 



function T StringToUser( ServPort : port; 
STime : String .255; 
var Index : integer; 
vafWhatlFound: integer) 
: User Time 
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Parameters: 

ServPort-TimcPort (service port to Time Server) 
ST/me-String to be converted to time. 

Index-Position in string to start scanning for time. Returns the first 
character past the end of the valid time string. 

WhatI Found-Returns what was parsed from the time string . 

Returns: 

Raises BadDateTime ifSTime malformed. 



T StringToInt 



Converts a string to an internal-time record 
Call: 



Parameters: 



Returns: 



function TStringToInt ( ServPort : port; 
STime : String .255; 
var Index : integer; 
var WhatlFound: integer) 
: Internal Time 



ServPort-TimePort (service port to Time Server) 
STime-Stnng to be converted to time. 

//^ex-Position in string to start scanning for time. Returns the first 
character past the end of the valid time string. 

WhatI Found-Returns what was parsed from the time string 
Raises BadDateTime if STime malformed 



TNever 

Returns the internal time value representing "never". 
Call: 

function TNever ( ServPort : Port) 
: Internal Time 



27 Aug 84 



Servers-109 



Parameters: 

ServPort-TimePort (service port to Time Server) 

Returns: 

InternalTime record representing Never. 



8.5 Valid Time Zones 

The valid time zones accepted by T.StringToUser and TStringToInt are, 



GMT 


Greenwich MeanTime 




UT 


UniversalTime (Same as GMT) 




NST 


Newfoundland Standard Time 


(-3:30) 


AST 


Atlantic Standard Time 


(-4 hours) 


ADT 


Atlantic Daylight Time 




EST 


Eastern Standard Time 


(-5 hours) 


EDT 


Eastern Daylight Time 




CST 


Central Standard Time 


(-6 hours) 


CDT 


Central Daylight Time 




MST 


Mountain Standard Time 


(-7 hours) 


MDT 


Mountain Daylight Time 




PST 


Pacific Standard Time 


(-8 hours) 


PDT 


Pacific Daylight Time 




YST 


Yukon Standard Time 


(-9 hours) 


YDT 


Yukon Daylight Time 




HST 


Hawaii- Alaska Standard Time 


(-10 hours) 


HDT 


Hawaii- Alaska Daylight Time 




BST 


Bering Standard Time 


(-11 hours) 


BDT 


Bering Daylight Time 
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9 The Typescript Manager 

9.1 Introduction 

The Typescript manager maintains standard text windows (Typescripts), providing line editing and 
redisplay functions for user programs that do not require graphics output or elaborate input control. 

Typescript remembers the last several pages (a window's worth) of text output by the program using a 
typescript. When a text window changes state, size, or coveredness, Typescript will also redisplay 
information that may have scrolled from the window. 

Typescript allows the user to edit input lines using a subset of the commands available in the system editor. 
The user can use all of the editor's single- line editing functions, and recall previous input lines to be edited 
into new input lines. 

Typescript also handles Escape Completion for each typescript The user may type a partial filename and 
press the Escape key; Typescript will ask the file system to complete the file name by finding the longest 
unambiguous match to the partial name. It will then add the name to the line of input, so that the user can 
specify the rest of the name or add more to the line. 

Typescript can either stop at the end of each screenful of output ('more' mode) or scroll output 
continuously. The user can select which mode to use, under keyboard control. 

In 'More' mode, when a full page of output has been displayed, a black bar appears at the bottom of the 
window. The user then presses LineFeed to display the next page of output 

In continuous scroll mode, the user can use the Process Control Functions Suspend and Resume to stop or 
start output 

9.2 Use 

Each typescript maintained by the Typescript manager has its own port. All requests for input output, and 
control of a typescript are directed to its port. There is a master typescript port used to create new 
typescripts. 

When a user program is started, the mater typescript port is TypescriptPort and the port associated with the 
program's window is UserTypescript. Both of these are in PascallnitPas. Pascal input and output through 
the default files INPUT and OUTPUT is directed to UserTypescript (unless input or output has been 
redirected). 

A program may create a new Typescript in an existing window by using the call STSOpen Window and 
providing it with the window to use. It returns a port for the typescript in that window. 

The program may then request a full line of input with STSGetString. This will allow the user to type a line 
of input using all of the line editing commands. When the user types RETURN, the line is finished and is 
returned to the program. 

A program may ouput a line of text by calling STSPutString, supplying the typescript and the string to 
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output. Each LineFeed chatacter in the string ends a line of text, scrolling the typescript and putting the 
ntext character at the start of the next line. The string does not need to end with a line feed. 
A program can ask the Tyepscript Manager to stop refreshing the screen. The call STSGrabWindow returns 
the window associated with the supplied typescript When the program is terminated, the Typcsscript 
Manager will resume control over the window and refresh it, erasing whatever the program had displayed 
on it 

Since each Typescrip may be used by a program or shell that has its own environment, a program can 
specify the environment connection to be used by the typescript This controls the list of files scanned for 
Escape Completion. Each Typescript has its own Environment Connection. 

9.3 Definitions 

The following definitions are from TSDefs.pas. 
type 

Typescript = Port; 
TString255 = String[255]; 

TSChar Array = packed array[0 .. 1] of Char; 
pTSCharArray = t TSCharArray; 

9.4 Routines 

The following routines are from TSUser.pas. 

STSOpen 

Creates a Typescript inside a viewport The typescript uses the system font, displays long lines by wrapping 
around, and stores three windows' worth of output 

Call: 

Function STSOpen( 

ServPort: Port; 
vp : viewport; 
env: Port) 
: Typescript 

Parameters: 

ServPort-ThQ master Typescript service port (TypescriptPort) 

vp-The viewport to contain the typescript 

env- An Environment Manager connection, used to define 
the environment for Escape Completion on this typescript 
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Returns: 



A port for a new typescript. 



STSOpenWindow 

Creates a Typescript inside a window. The typescript uses the system font, displays long lines by wrapping 
around, and stores three windows' worth of output. 

Call: 

Function STSOpen( 

ServPort: Port; 
w : window; 
env: Port) 
: Typescript 



Parameters: 



Returns: 



ServPort-The master Typescript service port (TypescriptPort) 

w-The window to contain the typescript 

env-An Environment Manager connection, used to define 
the environment for Escape Completion on this typescript 

A port for a new typescript 



STSFuIlOpen 

Creates a Typescript inside a viewport, allowing the program to select more parameters for the typescript 
Call: 



Parameters: 



Function STSFullOpen( 

ServPort: Port; 
vp : viewport; 
env: Port; 
fontName: TString255; 
doWrap : Boolean; 
dispPages : Integer) 
: Typescript 



ServPort-The master Typescript service port (TypescriptPort) 
vp-The viewport to contain the typescript. 
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env-An Environment Manager connection, used to define 
the environment for Escape Completion on this typescript 

fontName-The name of the font containing the font to use for the 
typescript It must be an absolute path name. 

doWrap-if TRUE, displays lines wider than the window by wrapping 
to the start of the next line. If FALSE, truncates long lines at the right 
margin of the window. 

Returns: 

A port for a new typescript. 



STSFuIIOpenWindow 

Creates a Typescript inside a window, allowing the program to select more parameters for the typescript. 
Call: 

Function STSFullOpen( 

v.i <x uu. run, 

w : Window; 
env: Port; 
fontName : TString255; 
doWrap : Boolean; 
dispPages : Integer) 
: Typescript 

Parameters: 

ServPort-The master Typescript service port (TypescriptPort) 

w-The window to contain the typescript 

env-An Environment Manager connection, used to define 
the environment for Escape Completion on this typescript 

fontName-The name of the font containing the font to use for the 
typescript It must be an absolute path name. 

doWrap-\f TRUE, displays lines wider than the window by wrapping 
to the start of the next line. If FALSE, truncates long lines at the right 
margin of the window. 

Returns: 

A port for a new typescript 
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STSGetChar 

Returns a singel character of input from a typescript. If a full line has not been typed, it invokes the line editor 
and waits until a line is completed If a line has been typed, it removes the next character from the start of the 
line and returns it 
Call: 

Function STSGetChar( 

ServPort: Typescript) 

: Char 

Parameters: 

ServPort-Port for the typescript 

Returns: 

The first character on the input line. 



STSGetString 

Returns an entire line of input from a typescript. If a full line has not been typed, it invokes the line editor and 
waits until a line is completed It then returns the entire line. 

Call: 

function STSGetString( 

ServPort : Typescript) 
: TString255 



Parameters: 



Returns: 



ServPort-Port for the typescript 
The entire input line. 



STSPutChar 

Writes a single character to a typescript. 
Call: 

Procedure STSPutChar( 

ServPort : Typescript; 
ch : Char) 

Parameters: 
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ServPort-The port for the typescript 

ch-The single character to output 
A LineFeed character ends the current output line. A BELL character (control G) flashes the viewport 
containing the typescript. Any other character is appended to the current line, possibly translated: 

Control character (chr(0)..chr( 13)) are displayed as tChar. 
DEL is displayed ast{. 

Printing characters (space through '} ) are displayed as 
themselves. 

Any character greater than chr(127) is displayed as the corresponding character in the font for the typescript, 
minus 128. This allows character in the font with numeric values less than 32 to be displayed as normal 
printing characters. 

STSPutString 

Writes a string of characters to a typescript. Each character in the string is displayed according to the 
description for STSPutChar. 

Cali: 

Procedure STSPutString( 

ServPort : Typescript; 
s : TString255) 

Parameters: 

ServPort-The port for the typescript 
s-The string to output 

STSFlushlnput 

Flushes any partially entered input line from a typescript 
Call: 

Procedure STSFlushInput( 

ServPort : Typescript) 

Parameters: 

ServPort-The port for the typescript 

STSFlushOutput 
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Forces any queued output for a Typescript to be displayed on the screen. STSPutChar and STSPutString may 
not display the output characters immediately, giving strange results if one tries to use the same viewport for 
simple text output and for graphics. STSFlushOutpul ensures that all Typescript output is displayed on the 
screen before it returns. 

Call: 

Procedure STSFlushOutput( 

ServPort : Typescript) 

Parameters: 

ServPort-The port for the typescript 



STSChangeEnv 

Changes the Environment connection associated with a typescript. The Environment connection determines 
the searchlists used for Escape Completion within that typescript. 

Parameters: 

ServPort-The port for the typescript 
env-The new Environment Connection to use. 



STSGrabWindow 

STSGrabWindow tells Typescript to stop monitoring the state of the window containing a Typescript for 
change is state, size or coveredness. A program such as the editor uses this procedure to gain control of the 
default user window to use it for graphics. When the program terminates, typescript regains control of the 
window and redisplays its contents as of the lime STSGrabWindow was called; any changes that the program 
made to the window are lost 

an: 

Function STSGrabWindow( 

ServPort : Typescript; 
kPort : Port) 
: Window 

Parameters: 

ServPort-The port for the typescript 

kPort-k port that the user program has ownership 
rights for or that will otherwise be deallocated when the 
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program terminates. Typescript regains control of the window 
when this port is deleted. 

Returns: 

The window that the Typescript is using. 
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